pdfh 3.3.0 → 4.0.0

data/lib/pdfh/services/document_manager.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Pdfh
+  module Services
+    # Manages the documents, rename, move, etc.
+    class DocumentManager
+      PDF_UNLOCKED_MAGIC_SUFFIX = "_unlocked"
+
+      # @param document [Document]
+      # @param base_path [String]
+      # @param dry_run [Boolean]
+      # @return [DocumentManager]
+      def initialize(document, base_path:, dry_run:)
+        @document = document
+        @base_path = base_path
+        @dry_run = dry_run
+      end
+
+      # @return [void]
+      def call
+        destination_dir = File.join(@base_path, @document.store_path)
+        destination_file = File.join(destination_dir, @document.new_name)
+
+        print_info(destination_dir) if Pdfh.logger.verbose?
+        create_destination_dir(destination_dir)
+        copy_pdf(destination_file)
+        move_companion_files(destination_dir)
+        backup_original
+      end
+
+      private
+
+      # @!attribute [r] document
+      #   @return [Document]
+      attr_reader :document
+
+      # @return [Boolean]
+      def dry_run? = @dry_run
+
+      # @param dir [String]
+      # @return [void]
+      def create_destination_dir(dir)
+        return if Dir.exist?(dir)
+
+        Pdfh.logger.debug "Creating directory: #{dir}"
+        FileUtils.mkdir_p(dir) unless @dry_run
+      end
+
+      # @param destination_file [String]
+      # @return [void]
+      def copy_pdf(destination_file)
+        source_file = @document.file_info.path
+
+        companion_extensions = companion_files.map { File.extname(_1).delete(".") }
+        companion_str = companion_extensions.any? ? " [#{companion_extensions.join(", ").colorize(:magenta)}]" : ""
+        message = format("[%<type>s] %<file>s -> %<dest>s#{companion_str}",
+                         type: document.type.name.ljust(15).colorize(:green),
+                         file: document.file_info.name.colorize(:blue),
+                         dest: document.new_name.colorize(:cyan))
+        if @dry_run
+          Pdfh.logger.info "#{"dry".colorize(:red)} #{message}" unless Pdfh.logger.verbose?
+          return
+        end
+
+        Pdfh.logger.info "#{"".colorize(:green)} #{message}" unless Pdfh.logger.verbose?
+        FileUtils.cp(source_file, destination_file, preserve: true)
+      end
+
+      # @param destination_dir [String]
+      # @return [void]
+      def move_companion_files(destination_dir)
+        companion_files.each do |companion|
+          source = companion
+          dest_name = File.basename(@document.new_name, @document.file_info.extension) + File.extname(companion)
+          destination = File.join(destination_dir, dest_name)
+
+          FileUtils.cp(source, destination, preserve: true) unless dry_run?
+        end
+      end
+
+      # @return [void]
+      def backup_original
+        source_file = document.file_info.path
+        backup_file = "#{source_file}.bkp"
+
+        FileUtils.mv(source_file, backup_file) unless dry_run?
+      end
+
+      # Finds companion files by removing the _unlocked suffix from the PDF name if present.
+      # This allows PDFs unlock by qpdf to locate their original companion files (e.g., .xml, .txt)
+      # that were never renamed with the _unlocked suffix.
+      #
+      # @return [Array<String>] array of non-PDF files with the same base name
+      # @example
+      #   # If document is "cuenta_unlocked.pdf", searches for "cuenta.*"
+      #   # Returns ["cuenta.xml", "cuenta.txt"] (excluding "cuenta.pdf")
+      def companion_files
+        @companion_files ||= begin
+          base_name = document.file_info.stem.delete_suffix(PDF_UNLOCKED_MAGIC_SUFFIX)
+          Dir.glob(File.join(document.file_info.dir, "#{base_name}.*")).reject do |file|
+            File.extname(file) == ".pdf"
+          end
+        end
+      end
+
+      # @param property [String]
+      # @param info [String]
+      # @return [void]
+      def print_info_line(property, info)
+        Pdfh.logger.ident_print property, info.to_s, color: :light_blue, width: 12
+      end
+
+      # @param destination_dir [String]
+      # @return [void]
+      def print_info(destination_dir)
+        print_info_line "Type", document.type.name
+        print_info_line "Period", document.date_info.period
+        print_info_line "New Name", document.new_name
+        print_info_line "Store Path", destination_dir
+        print_info_line "Extra files", companion_files.any? ? companion_files.join(", ") : "—"
+        print_info_line "Processed?", "No (in Dry mode)" if dry_run?
+      end
+    end
+  end
+end

data/lib/pdfh/services/document_matcher.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Pdfh
+  module Services
+    # Matches a PDF file against settings and builds a Document if valid
+    class DocumentMatcher
+      # @param document_types [Array<DocumentType>]
+      # @return [DocumentMatcher]
+      def initialize(document_types)
+        @document_types = document_types
+      end
+
+      # @param file [String] Path to the PDF file
+      # @param text [String] Extracted text from the PDF
+      # @return [Array<Document>]
+      def match(file, text)
+        @document_types.each_with_object([]) do |type, matches|
+          # Try to match the document type by ID (content)
+          next unless type.re_id.match?(text)
+
+          Pdfh.logger.debug "Matched document type: #{type.name}"
+
+          # Try to match the date in the text
+          date_match = type.re_date.match(text)
+          unless date_match
+            Pdfh.logger.debug "No date match found for #{type.name}"
+            next
+          end
+
+          # Extract date captures (handles both named and positional captures)
+          date_captures = extract_date_captures(date_match)
+
+          matches << Document.new(file, type, text, date_captures)
+        end
+      end
+
+      private
+
+      # Extracts date captures from MatchData, supporting both named and positional captures
+      # @param match_data [MatchData]
+      # @return [Hash{String => String}] Hash with keys 'm' (month), 'y' (year), 'd' (day)
+      def extract_date_captures(match_data)
+        if match_data.names.any?
+          Pdfh.logger.debug "Using #{"named".colorize(:green)} captures: #{match_data.named_captures.inspect}"
+          return match_data.named_captures
+        end
+
+        # Fall back to positional captures — assume order: [month, year, day?]
+        {}.tap do |c|
+          c["m"], c["y"], c["d"] = match_data.captures
+          c.compact!
+          Pdfh.logger.debug "Using #{"positional".colorize(:red)} captures: #{c.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/pdfh/services/opt_parser.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Pdfh
+  module Services
+    # Handles Argument options
+    class OptParser
+      # @param argv [Array<String>] command line arguments (ie. ARGV)
+      # @param console [Pdfh::Console, nil]
+      # @return [self]
+      def initialize(argv:, console: nil)
+        @argv = argv
+        @console = console || Console.new(false)
+        @options = {
+          verbose: false,
+          dry: false
+        }
+      end
+
+      # @return [Hash] Parsed options including flags and file arguments
+      def parse_argv
+        option_parser = build_option_parser
+        option_parser.parse!(@argv)
+        @options
+      rescue OptionParser::InvalidOption => e
+        @console.error_print(e.message, exit_app: false)
+        @console.info option_parser.help
+        exit 1
+      end
+
+      private
+
+      # @return [OptionParser] Configured OptionParser instance
+      def build_option_parser
+        OptionParser.new do |opts|
+          opts.banner = "Usage: #{opts.program_name} [options]"
+          opts.separator ""
+          opts.separator "Specific options:"
+
+          opts.on("-v", "--verbose", "Show more output. Useful for debug") { @options[:verbose] = true }
+          opts.on("-d", "--dry", "Dry run, does not write new pdf") { @options[:dry] = true }
+          opts.on_tail("-T", "--list-types", "List document types in configuration") { list_types && exit }
+          opts.on_tail("-V", "--version", "Show version") { version || exit }
+          opts.on_tail("-h", "--help", "help (this dialog)") { help || exit }
+        end
+      end
+
+      # @return [nil]
+      def version
+        @console.info "#{build_option_parser.program_name} v#{Pdfh::VERSION}"
+      end
+
+      # @return [nil]
+      def help
+        @console.info build_option_parser
+      end
+
+      # Lists the available document types
+      # @return [nil]
+      def list_types
+        # Temporarily set logger for loading settings
+        Pdfh.logger = @console
+
+        settings = SettingsBuilder.call
+        spacing = " " * 2
+        max_width = settings.document_types.map { |t| t.gid.size }.max
+        @console.info "#{spacing}#{"ID".ljust(max_width)}  Type Name"
+        @console.info "#{spacing}#{"—" * max_width}  #{"—" * 23}"
+        settings.document_types.each do |type|
+          @console.info "#{spacing}#{type.gid.ljust(max_width).yellow}  #{type.name}"
+        end
+      end
+    end
+  end
+end

data/lib/pdfh/services/pdf_text_extractor.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require "english"
+
+module Pdfh
+  module Services
+    # Extracts text from a PDF using pdftotext command
+    class PdfTextExtractor
+      # @param pdf_path [String]
+      # @return [String]
+      # @raise [ArgumentError] if file doesn't exist or is not a PDF
+      # @raise [RuntimeError] if extraction fails
+      def self.call(pdf_path)
+        validate_file!(pdf_path)
+
+        # Use Shellwords to properly escape the path for shell execution
+        safe_path = Shellwords.escape(pdf_path)
+        cmd = "pdftotext -enc UTF-8 -layout #{safe_path} - 2>/dev/null"
+
+        text = `#{cmd}`
+        exit_status = $CHILD_STATUS
+
+        # Check if command executed successfully
+        if exit_status.nil? || !exit_status.success?
+          Pdfh.logger.debug "Failed to extract text from: #{pdf_path}"
+          return ""
+        end
+
+        text
+      end
+
+      # @param pdf_path [String]
+      # @return [void]
+      # @raise [ArgumentError] if validation fails
+      def self.validate_file!(pdf_path)
+        raise ArgumentError, "PDF path cannot be nil" if pdf_path.nil?
+        raise ArgumentError, "PDF path cannot be empty" if pdf_path.empty?
+        raise ArgumentError, "File does not exist: #{pdf_path}" unless File.exist?(pdf_path)
+        raise ArgumentError, "Not a file: #{pdf_path}" unless File.file?(pdf_path)
+        raise ArgumentError, "Not a PDF file: #{pdf_path}" unless File.extname(pdf_path).casecmp?(".pdf")
+      end
+    end
+  end
+end

data/lib/pdfh/services/settings_builder.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Pdfh
+  module Services
+    # Loads or creates a default settings yaml file
+    class SettingsBuilder
+      CONFIG_FILE_LOCATIONS = [Dir.pwd, ENV.fetch("XDG_CONFIG_HOME", "~/.config"), "~"].freeze
+      SUPPORTED_EXTENSIONS = %w[yml yaml].freeze
+      ENV_VAR = "PDFH_CONFIG_FILE"
+
+      DOCUMENT_TYPE_TEMPLATE = {
+        name: "Example Name",
+        re_id: "EXAMPLE MATCH",
+        re_date: "(\d{2})/(?<m>\w+)/(?<y>\d{4})",
+        store_path: "{YEAR}/sub folder",
+        name_template: "{period} {original}"
+      }.freeze
+
+      SETTINGS_TEMPLATE = {
+        lookup_dirs: ["~/Downloads"].freeze,
+        destination_base_path: "~/Documents",
+        document_types: [DOCUMENT_TYPE_TEMPLATE].freeze
+      }.freeze
+
+      # @param program_name [String, nil] Override for testing (defaults to PROGRAM_NAME)
+      # @return [Settings]
+      def self.call(program_name: nil)
+        new(program_name: program_name).call
+      end
+
+      # @param program_name [String, nil]
+      # @return [SettingsBuilder]
+      def initialize(program_name: nil)
+        @program_name = program_name || PROGRAM_NAME
+      end
+
+      # @return [Settings]
+      def call
+        config_file = find_config_file
+        file_hash = YAML.load_file(config_file, symbolize_names: true)
+        Pdfh.logger.debug "Loaded configuration file: #{config_file}"
+
+        validated = Services::SettingsValidator.call(file_hash)
+        Settings.new(**validated)
+      end
+
+      private
+
+      # @return [String]
+      def find_config_file
+        env_config_file = ENV.fetch(ENV_VAR, nil)
+
+        if env_config_file
+          unless File.exist?(env_config_file)
+            raise SettingsIOError,
+                  "File path in #{ENV_VAR} not found: #{env_config_file}"
+          end
+
+          return env_config_file
+        end
+
+        search_config_file || create_settings_file
+      end
+
+      # @return [String]
+      def config_file_name
+        File.basename(@program_name, ".*")
+      end
+
+      # @return [String]
+      def default_settings_name
+        "#{config_file_name}.#{SUPPORTED_EXTENSIONS.first}"
+      end
+
+      # @return [String]
+      def create_settings_file
+        full_path = File.join(File.expand_path("~"), default_settings_name)
+        return full_path if File.exist?(full_path) # double check
+
+        File.write(full_path, stringify_keys(SETTINGS_TEMPLATE).to_yaml)
+        Pdfh.logger.info "Default settings file was created: #{full_path.colorize(:green)}"
+
+        full_path
+      end
+
+      # Recursively converts symbol keys to string keys for YAML serialization
+      # @param value [Hash, Array, Object]
+      # @return [Hash, Array, Object]
+      def stringify_keys(value)
+        case value
+        when Hash then value.to_h { |k, v| [k.to_s, stringify_keys(v)] }
+        when Array then value.map { |v| stringify_keys(v) }
+        else value
+        end
+      end
+
+      # Gets the first settings file found, or nil
+      # @return [String, nil]
+      def search_config_file
+        CONFIG_FILE_LOCATIONS.each do |dir_string|
+          dir = File.expand_path(dir_string)
+          SUPPORTED_EXTENSIONS.each do |ext|
+            path = File.join(dir, "#{config_file_name}.#{ext}")
+            return path if File.exist?(path)
+          end
+        end
+
+        Pdfh.logger.warn_print "No configuration file was found within paths: #{CONFIG_FILE_LOCATIONS.join(", ")}"
+        nil
+      end
+    end
+  end
+end

data/lib/pdfh/services/settings_validator.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Pdfh
+  module Services
+    # Validates and processes raw configuration data from YAML into clean,
+    # validated attributes ready for Settings construction.
+    class SettingsValidator
+      # @param config_data [Hash] Raw configuration hash from YAML
+      # @return [Hash] Validated and processed attributes for Settings
+      # @raise [ArgumentError] if configuration is invalid
+      def self.call(config_data)
+        new(config_data).call
+      end
+
+      # @param config_data [Hash]
+      # @return [Self]
+      def initialize(config_data)
+        @config_data = config_data
+      end
+
+      # @return [Hash{Symbol => Object}] with keys :lookup_dirs, :base_path, :document_types
+      def call
+        {
+          lookup_dirs: process_lookup_dirs(@config_data[:lookup_dirs]),
+          base_path: process_destination_base(@config_data[:destination_base_path]),
+          document_types: build_doc_types(@config_data[:document_types])
+        }
+      end
+
+      private
+
+      # Expands and validates a directory. Returns nil if invalid.
+      # @param dir [String, nil]
+      # @return [String, nil]
+      def expand_directory(dir)
+        return nil unless dir.is_a?(String) && !dir.strip.empty?
+
+        expanded = File.expand_path(dir)
+        File.directory?(expanded) ? expanded : nil
+      end
+
+      # Same as expand_directory but raises on failure.
+      # @param dir [String, nil]
+      # @param label [String] used in the error message
+      # @return [String]
+      # @raise [ArgumentError]
+      def expand_directory!(dir, label:)
+        expand_directory(dir) || raise(ArgumentError, "#{label} is invalid or does not exist: #{dir.inspect}")
+      end
+
+      # @param lookup_dirs_list [Array<String>]
+      # @return [Array<String>]
+      def process_lookup_dirs(lookup_dirs_list)
+        validate_lookup_dirs_type(lookup_dirs_list)
+
+        dirs = lookup_dirs_list.filter_map do |dir|
+          expanded = expand_directory(dir)
+          Pdfh.logger.warn_print "lookup_dirs: #{dir.inspect} does not exist, skipping." unless expanded
+          expanded
+        end
+        raise ArgumentError, "No valid lookup_dirs configured." if dirs.empty?
+
+        Pdfh.logger.debug "Configured Look up directories:"
+        dirs.each.with_index(1) { |dir, idx| Pdfh.logger.debug "  #{idx}. #{dir}" }
+        Pdfh.logger.debug
+
+        dirs
+      end
+
+      # @param lookup_dirs_list [Array, nil]
+      # @return [void]
+      # @raise [ArgumentError] if lookup_dirs_list is invalid
+      def validate_lookup_dirs_type(lookup_dirs_list)
+        raise ArgumentError, "Look up directories are not configured." if lookup_dirs_list.nil?
+        raise ArgumentError, "Look up directories must be an array of strings." unless lookup_dirs_list.is_a?(Array)
+        return if lookup_dirs_list.all?(String)
+
+        raise ArgumentError, "Look up directories must be an array of strings."
+      end
+
+      # @param dir [String, nil]
+      # @return [String]
+      def process_destination_base(dir)
+        expand_directory!(dir, label: "destination_base_path")
+      end
+
+      # @param doc_types [Array<Hash>]
+      # @return [Hash{String => DocumentType}]
+      def build_doc_types(doc_types)
+        validate_doc_types_type(doc_types)
+        doc_types = parse_doc_types(doc_types)
+        raise ArgumentError, "No valid document types configured." if doc_types.empty?
+
+        doc_types
+      end
+
+      # @param doc_types [Array, nil]
+      # @return [void]
+      # @raise [ArgumentError] if doc_types is invalid
+      def validate_doc_types_type(doc_types)
+        raise ArgumentError, "Document types are not configured." if doc_types.nil?
+        raise ArgumentError, "Document types must be an array." unless doc_types.is_a?(Array)
+        raise ArgumentError, "Document types must be an array of hashes." unless doc_types.all?(Hash)
+      end
+
+      # @param doc_types [Array<Hash>]
+      # @return [Hash{String => DocumentType}]
+      def parse_doc_types(doc_types)
+        doc_types.each_with_object({}) do |data, result|
+          doc_type = build_doc_type(data)
+          result.store(doc_type.gid, doc_type) if doc_type
+        rescue StandardError => e
+          Pdfh.logger.error_print e.message, exit_app: false
+          Pdfh.logger.backtrace_print e if Pdfh.logger.verbose?
+        end
+      end
+
+      # @param data [Hash]
+      # @return [DocumentType, nil] Document type when valid, otherwise nil.
+      def build_doc_type(data)
+        doc_type = DocumentType.new(data)
+        return doc_type if doc_type.valid?
+
+        log_doc_type_errors(doc_type)
+        nil
+      end
+
+      # @param doc_type [DocumentType]
+      # @return [void]
+      def log_doc_type_errors(doc_type)
+        doc_type_name = doc_type.name.to_s.colorize(:blue)
+
+        if doc_type.missing_keys?
+          missing = doc_type.missing_keys.join(", ").colorize(:red)
+          Pdfh.logger.info "Document type '#{doc_type_name}' is missing required keys: #{missing}"
+        end
+
+        unless doc_type.path_validator.valid?
+          unknown = doc_type.store_path.unknown_list
+          Pdfh.logger.info "Document type '#{doc_type_name}', path_validator has invalid keys: #{unknown}"
+        end
+
+        return if doc_type.name_validator.valid?
+
+        unknown = doc_type.name_template.unknown_list
+        Pdfh.logger.info "Document type '#{doc_type_name}', name_validator has invalid keys: #{unknown}"
+      end
+    end
+  end
+end

data/lib/pdfh/utils/console.rb

@@ -41,10 +41,10 @@ module Pdfh
       exit 1 if exit_app
     end
 
-    # @param e [StandardError]
+    # @param error [StandardError]
     # @return [void]
-    def backtrace_print(e)
-      e.backtrace&.each do |line|
+    def backtrace_print(error)
+      error.backtrace&.each do |line|
         output "  ↳ #{line.sub("#{Dir.pwd}/", "")}".colorize(:light_black)
       end
     end
@@ -87,13 +87,13 @@ module Pdfh
       nil
     end
 
-    private
-
     # @return [boolean]
     def verbose?
       @verbose
     end
 
+    private
+
     # @return [void]
     def output(msg)
       puts(msg)

data/lib/pdfh/utils/date_info.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Pdfh
+  # Encapsulates date interpretation from regex captures.
+  # Responsible for converting raw captured strings into typed date values
+  # and deriving period groupings (quarter, bimester, period string).
+  class DateInfo
+    # @param date_captures [Hash{String => String}] Captured date components.
+    #   Keys: "m" (month — name or number), "y" (year — 2 or 4 digits), "d" (day, optional)
+    # @return [self]
+    def initialize(date_captures)
+      @date_captures = date_captures
+    end
+
+    # @return [Hash{String => String}] Raw date captures as provided by the regex match
+    def captures
+      @date_captures
+    end
+
+    # @return [Integer] Normalized month number (1–12)
+    def month
+      @month ||= Month.normalize_to_i(@date_captures["m"])
+    end
+
+    # @return [Integer] Full four-digit year (e.g., 2024)
+    def year
+      @year ||= begin
+        raw = @date_captures["y"]
+        (raw.size == 2 ? "20#{raw}" : raw).to_i
+      end
+    end
+
+    # @return [String, nil] Day of month if captured, nil otherwise
+    def day
+      @date_captures["d"]
+    end
+
+    # Q1: Jan–Mar, Q2: Apr–Jun, Q3: Jul–Sep, Q4: Oct–Dec
+    # @return [Integer] Quarter (1–4) based on the month
+    def quarter
+      @quarter ||= ((month - 1) / 3) + 1
+    end
+
+    # B1: Jan–Feb, B2: Mar–Apr, B3: May–Jun, B4: Jul–Aug, B5: Sep–Oct, B6: Nov–Dec
+    # @return [Integer] Bimester (1–6) based on the month
+    def bimester
+      @bimester ||= ((month - 1) / 2) + 1
+    end
+
+    # @return [String] Period in format "YYYY-MM"
+    def period
+      "#{year}-#{month.to_s.rjust(2, "0")}"
+    end
+  end
+end