appydave-tools 0.84.0 → 0.86.0

data/lib/appydave/tools/app_context/app_finder.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Appydave
+  module Tools
+    module AppContext
+      # Queries locations.json to find app files via context.globs.json patterns.
+      #
+      # Follows the same find/find_meta pattern as BrainQuery and OmiQuery.
+      class AppQuery
+        def initialize(options, jump_config: nil)
+          @options = options
+          @jump_config = jump_config
+        end
+
+        # Return absolute file paths matching the query
+        def find
+          return [] unless @options.query?
+
+          apps = resolve_apps
+          return [] if apps.empty?
+
+          apps.flat_map { |app| expand_app(app) }.uniq.sort
+        end
+
+        # Return structured metadata about the query results
+        def find_meta
+          return [] unless @options.query?
+
+          apps = resolve_apps
+          return [] if apps.empty?
+
+          apps.map { |app| build_meta(app) }
+        end
+
+        # List all available glob names for a specific app
+        def list_globs(app_name)
+          location = find_location(app_name)
+          return [] unless location
+
+          loader = build_loader(location)
+          return [] unless loader.available?
+
+          loader.available_names
+        end
+
+        # List all apps that have context.globs.json
+        def list_apps
+          jump_config.locations
+                     .select { |loc| File.exist?(File.join(expand_path(loc.path), 'context.globs.json')) }
+                     .map do |loc|
+                       loader = build_loader(loc)
+                       {
+                         'key' => loc.key,
+                         'path' => expand_path(loc.path),
+                         'pattern' => loader.pattern,
+                         'glob_count' => loader.globs.size
+                       }
+                     end
+        end
+
+        private
+
+        def jump_config
+          @jump_config ||= Jump::Config.new
+        end
+
+        # Resolve app names to Location objects
+        def resolve_apps
+          if @options.pattern_filter
+            resolve_by_pattern(@options.pattern_filter)
+          else
+            @options.app_names.flat_map { |name| resolve_app(name) }.compact.uniq(&:key)
+          end
+        end
+
+        # 4-tier app resolution
+        def resolve_app(name)
+          name_down = name.downcase
+
+          # Tier 1: exact key match
+          loc = jump_config.find(name_down)
+          return [loc] if loc
+
+          # Tier 2: jump alias match
+          loc = jump_config.locations.find { |l| l.jump&.downcase == name_down }
+          return [loc] if loc
+
+          # Tier 3: substring match on key
+          matches = jump_config.locations.select { |l| l.key.downcase.include?(name_down) }
+          return matches unless matches.empty?
+
+          # Tier 4: substring match on description
+          jump_config.locations.select { |l| l.description&.downcase&.include?(name_down) }
+        end
+
+        def resolve_by_pattern(pattern)
+          jump_config.locations.select do |loc|
+            loader = build_loader(loc)
+            loader.available? && loader.pattern&.downcase == pattern.downcase
+          end
+        end
+
+        def expand_app(location)
+          loader = build_loader(location)
+          return [] unless loader.available?
+
+          glob_names = @options.glob_names
+          return [] if glob_names.empty?
+
+          loader.expand(glob_names)
+        end
+
+        def build_meta(location)
+          loader = build_loader(location)
+          glob_names = @options.glob_names
+          file_count = loader.available? && glob_names.any? ? loader.expand(glob_names).size : 0
+
+          resolved_from = glob_names.map { |n| describe_resolution(loader, n) }.join(', ')
+
+          {
+            'app' => location.key,
+            'path' => expand_path(location.path),
+            'pattern' => loader.pattern,
+            'matched_globs' => resolve_glob_names(loader, glob_names),
+            'resolved_from' => resolved_from,
+            'file_count' => file_count
+          }
+        end
+
+        def build_loader(location)
+          GlobsLoader.new(expand_path(location.path))
+        end
+
+        def expand_path(path)
+          File.expand_path(path)
+        end
+
+        def find_location(app_name)
+          results = resolve_app(app_name)
+          results&.first
+        end
+
+        # Describe how a glob name was resolved (for meta output)
+        def describe_resolution(loader, name)
+          name = name.strip.downcase
+          return "#{name} (glob)" if loader.globs.key?(name)
+          return "#{name} (alias)" if loader.aliases.key?(name)
+          return "#{name} (composite)" if loader.composites.key?(name)
+
+          "#{name} (fuzzy)"
+        end
+
+        # Resolve glob names to their constituent direct glob names
+        def resolve_glob_names(loader, names)
+          return [] unless loader.available?
+
+          names.flat_map do |name|
+            name = name.strip.downcase
+            if loader.globs.key?(name)
+              [name]
+            elsif loader.aliases.key?(name)
+              loader.aliases[name]
+            elsif loader.composites.key?(name)
+              members = loader.composites[name]
+              members == ['*'] ? loader.globs.keys : members
+            else # rubocop:disable Lint/DuplicateBranch
+              [name]
+            end
+          end.uniq
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/app_context/globs_loader.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Appydave
+  module Tools
+    module AppContext
+      # Loads and resolves named glob patterns from a context.globs.json file.
+      #
+      # Resolution is 3-tier:
+      #   1. Direct glob name  — "services" → globs["services"]
+      #   2. Alias match       — "backend"  → aliases["backend"] → ["services", "routes"]
+      #   3. Composite match   — "understand" → composites["understand"] → ["context", "docs", ...]
+      class GlobsLoader
+        attr_reader :project_path, :data
+
+        def initialize(project_path)
+          @project_path = project_path
+          @data = load_globs_file
+        end
+
+        def available?
+          !data.nil?
+        end
+
+        def globs
+          data&.fetch('globs', {}) || {}
+        end
+
+        def aliases
+          data&.fetch('aliases', {}) || {}
+        end
+
+        def composites
+          data&.fetch('composites', {}) || {}
+        end
+
+        def pattern
+          data&.fetch('pattern', nil)
+        end
+
+        def project_name
+          data&.fetch('project', nil)
+        end
+
+        # List all available glob names (direct + aliases + composites)
+        def available_names
+          names = globs.keys.map { |k| { name: k, type: 'glob' } }
+          names += aliases.keys.map { |k| { name: k, type: 'alias' } }
+          names += composites.keys.map { |k| { name: k, type: 'composite' } }
+          names
+        end
+
+        # Resolve a single name through the 3-tier hierarchy.
+        # Returns an array of raw glob patterns (strings).
+        def resolve(name)
+          name = name.strip.downcase
+
+          # Tier 1: direct glob name
+          return globs[name] if globs.key?(name)
+
+          # Tier 2: alias → list of glob names
+          return aliases[name].flat_map { |glob_name| globs[glob_name] || [] } if aliases.key?(name)
+
+          # Tier 3: composite → list of glob names (or "*" for all)
+          if composites.key?(name)
+            members = composites[name]
+            return globs.values.flatten if members == ['*']
+
+            return members.flat_map { |glob_name| resolve_single_glob(glob_name) }
+          end
+
+          # Tier 4: substring fallback
+          match = find_substring_match(name)
+          return resolve(match) if match
+
+          []
+        end
+
+        # Resolve multiple names, expand globs against the filesystem, return absolute paths.
+        def expand(names)
+          patterns = names.flat_map { |name| resolve(name) }.uniq
+
+          patterns.flat_map { |pat| Dir.glob(File.join(project_path, pat)) }
+                  .select { |f| File.file?(f) }
+                  .uniq
+                  .sort
+        end
+
+        private
+
+        def globs_file_path
+          File.join(project_path, 'context.globs.json')
+        end
+
+        def load_globs_file
+          path = globs_file_path
+          return nil unless File.exist?(path)
+
+          JSON.parse(File.read(path))
+        rescue JSON::ParserError
+          nil
+        end
+
+        def resolve_single_glob(glob_name)
+          globs[glob_name] || []
+        end
+
+        def find_substring_match(name)
+          all_names = globs.keys + aliases.keys + composites.keys
+          all_names.find { |n| n.include?(name) }
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/app_context/options.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module AppContext
+      # Options struct for app context query tool
+      class Options
+        attr_accessor :app_names, :glob_names, :pattern_filter,
+                      :meta, :list, :list_apps,
+                      :debug_level
+
+        def initialize
+          @app_names = []
+          @glob_names = []
+          @pattern_filter = nil
+          @meta = false
+          @list = false
+          @list_apps = false
+          @debug_level = 'none'
+        end
+
+        def query?
+          app_names.any? || !pattern_filter.nil?
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/bank_reconciliation/_doc.md

@@ -0,0 +1,36 @@
+# Bank reconciliation
+
+[ChatGPT conversation](https://chatgpt.com/c/5d382562-95e5-4243-9b74-c3807d363486)
+
+
+## Code structure
+
+```bash
+├─ lib
+│ ├─ appydave
+│ │ └─ tools
+│ │   ├─ bank_reconciliation
+│ │   │ ├─ clean
+│ │   │ │ ├─ read_transactions.rb
+│ │   │ │ ├─ transaction_cleaner.rb
+│ │   │ ├─ models
+│ │   │ │ ├─ raw_transaction.rb
+│ │   │ │ └─ reconciled_transaction.rb
+│ │   └─ configuration
+│ │     └─ models
+│ │       └─ bank_reconciliation_config.rb
+└─ spec
+  ├─ appydave
+  │ ├─ tools
+  │ │ ├─ bank_reconciliation
+  │ │ │ ├─ clean
+  │ │ │ │ ├─ read_transactions_spec.rb
+  │ │ │ ├─ models
+  │ │ │ │ └─ raw_transaction_spec.rb
+  │ │ └─ configuration
+  │ │   └─ models
+  │ │     └─ bank_reconciliation_config_spec.rb
+  └─ fixtures
+    └─ bank-reconciliation
+      └─ bank-west.csv
+```

data/lib/appydave/tools/bank_reconciliation/clean/clean_transactions.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'clipboard'
+
+module Appydave
+  module Tools
+    module BankReconciliation
+      module Clean
+        # Clean transactions
+        class CleanTransactions
+          include KLog::Logging
+          include Appydave::Tools::Configuration::Configurable
+          include Appydave::Tools::Debuggable
+
+          attr_reader :transaction_folder
+          attr_reader :output_folder
+          attr_reader :transactions
+
+          # (config_file)
+          def initialize(transaction_folder: nil, output_folder: nil, debug: false)
+            @debug = debug
+            # needs to use config.bank_reconciliation.transaction_folder
+            transaction_folder ||= '/Volumes/Expansion/Sync/bank-reconciliation/original-transactions'
+            output_folder ||= File.join(transaction_folder, 'clean')
+
+            @transaction_folder = transaction_folder
+            @output_folder = output_folder
+          end
+
+          def clean_transactions(input_globs, output_file)
+            log_info("Starting transaction cleaning with input patterns: #{input_globs}")
+
+            raw_transactions = grab_raw_transactions(input_globs)
+            log_info("Total raw transactions collected: #{raw_transactions.size}")
+
+            transactions, duplicates_count = deduplicate_across_files(raw_transactions)
+            log_info("Duplicates found and removed: #{duplicates_count}")
+
+            transactions = Mapper.new.map(transactions)
+            log_info('Transactions mapped to chart of accounts and bank accounts')
+
+            log_kv 'Deduped consolidated transactions', duplicates_count if duplicates_count.positive?
+
+            save_to_csv(transactions, output_file)
+
+            csv_to_clipboard(output_file)
+
+            @transactions = transactions
+          end
+
+          private
+
+          def grab_raw_transactions(input_globs)
+            original_dir = Dir.pwd
+            transactions = []
+
+            begin
+              Dir.chdir(transaction_folder)
+
+              input_globs.each do |glob|
+                Dir.glob(glob).each do |file|
+                  log_kv 'Reading transactions from', file
+                  raw_transactions = ReadTransactions.new(file).read
+                  deduped_transactions, duplicates_count = deduplicate_within_file(raw_transactions)
+
+                  if duplicates_count.positive?
+                    log_kv 'Duplicates count within file', duplicates_count
+                    log_kv 'File', file
+                  end
+
+                  transactions += deduped_transactions
+                end
+              end
+            ensure
+              Dir.chdir(original_dir)
+            end
+
+            transactions
+          end
+
+          def deduplicate_within_file(transactions)
+            unique_transactions = transactions.uniq do |transaction|
+              [
+                transaction.bsb_number,
+                transaction.account_number,
+                transaction.transaction_date,
+                transaction.narration,
+                transaction.cheque_number,
+                transaction.debit,
+                transaction.credit,
+                transaction.balance,
+                transaction.transaction_type
+              ]
+            end
+
+            duplicates = transactions.size - unique_transactions.size
+
+            [unique_transactions, duplicates]
+          end
+
+          def deduplicate_across_files(transactions)
+            grouped_transactions = transactions.group_by do |transaction|
+              [
+                transaction.bsb_number,
+                transaction.account_number,
+                transaction.transaction_date,
+                transaction.narration,
+                transaction.cheque_number,
+                transaction.debit,
+                transaction.credit,
+                transaction.balance,
+                transaction.transaction_type
+              ]
+            end
+
+            unique_transactions = []
+            duplicates_count = 0
+
+            grouped_transactions.each_value do |dupes|
+              unique_transaction = dupes.first
+              unique_transaction.source_files = dupes.flat_map(&:source_files).uniq
+              duplicates_count += dupes.size - 1
+              unique_transactions << unique_transaction
+            end
+
+            [unique_transactions, duplicates_count]
+          end
+
+          def full_output_file(output_file)
+            File.join(output_folder, output_file)
+          end
+
+          def save_to_csv(transactions, output_file)
+            FileUtils.mkdir_p(output_folder)
+            output_file = full_output_file(output_file)
+            # puts "Output file: #{output_file}"
+
+            # lets sort the transactions by the by the transaction date which is formated as 2023-07-10
+            transactions.sort_by!(&:transaction_date)
+
+            CSV.open(output_file, 'w') do |csv|
+              csv << Appydave::Tools::BankReconciliation::Models::Transaction.csv_headers
+              transactions.each do |transaction|
+                csv << transaction.to_csv_row
+              end
+            end
+
+            log_kv('Transaction Output File', full_output_file(output_file))
+          end
+
+          def csv_to_clipboard(output_file)
+            Clipboard.copy(File.read(full_output_file(output_file)))
+            log_info('Transactions copied to clipboard')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/bank_reconciliation/clean/mapper.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module BankReconciliation
+      module Clean
+        # Map transactions to chart of accounts and bank accounts
+        class Mapper
+          include Appydave::Tools::Configuration::Configurable
+
+          def map(transactions)
+            # tp transactions, :coa_match_type, :coa_code, :narration, :debit, :credit
+            transactions.map do |original_transaction|
+              transaction = original_transaction.dup
+
+              transaction = map_chart_of_account(transaction)
+              clean_amount(transaction)
+              map_bank_account(transaction)
+            end
+          end
+
+          private
+
+          def map_chart_of_account(transaction)
+            equality_match(transaction) ||
+              trigram_match(transaction, 0.9, '90%') ||
+              trigram_match(transaction, 0.8, '80%') ||
+              trigram_match(transaction, 0.7, '70%') ||
+              trigram_match(transaction, 0.6, '60%') ||
+              trigram_match(transaction, 0.5, '50%') ||
+              start_with_match(transaction) ||
+              includes(transaction)
+            transaction
+          end
+
+          def map_bank_account(transaction)
+            bank_account = config.bank_reconciliation.get_bank_account(transaction.account_number, transaction.bsb_number)
+
+            if bank_account
+              transaction.account_name = bank_account.name
+              transaction.platform = bank_account.platform
+            else
+              puts "Bank account not found for BSB#: #{transaction.bsb_number} | Account#: #{transaction.account_number}"
+            end
+
+            transaction
+          end
+
+          def equality_match(transaction)
+            coa = config.bank_reconciliation.chart_of_accounts.find do |chart_of_account|
+              chart_of_account.narration.to_s.delete(' ').downcase == transaction.narration.delete(' ').downcase
+            end
+
+            return nil unless coa
+
+            transaction.coa_match_type = 'equality'
+            transaction.coa_code = coa.code
+            transaction
+          end
+
+          def start_with_match(transaction)
+            coa = config.bank_reconciliation.chart_of_accounts.find do |chart_of_account|
+              transaction.narration.to_s.delete(' ').downcase.start_with?(chart_of_account.narration.to_s.downcase)
+            end
+
+            return nil unless coa
+
+            transaction.coa_match_type = 'starts_with'
+            transaction.coa_code = coa.code
+            transaction
+          end
+
+          def includes(transaction)
+            coa = config.bank_reconciliation.chart_of_accounts.find do |chart_of_account|
+              transaction.narration.to_s.delete(' ').downcase.include?(chart_of_account.narration.delete(' ').to_s.downcase)
+            end
+
+            return nil unless coa
+
+            transaction.coa_match_type = 'includes'
+            transaction.coa_code = coa.code
+            transaction
+          end
+
+          def trigram_match(transaction, score_threshold, match_type)
+            scored_transactions = config.bank_reconciliation.chart_of_accounts.map do |coa|
+              {
+                coa: coa,
+                score: compare(coa.narration, transaction.narration)
+              }
+            end
+
+            scored_transactions.sort_by! { |t| t[:score] }.reverse!
+
+            best = scored_transactions.first
+
+            return nil unless best
+            return nil if best[:score] < score_threshold
+
+            coa = best[:coa]
+
+            transaction.coa_match_type = match_type
+            transaction.coa_code = coa.code
+            transaction
+          end
+
+          def compare(text1, text2)
+            text1_trigs = trigramify(text1)
+            text2_trigs = trigramify(text2)
+
+            all_cnt = (text1_trigs | text2_trigs).size
+            same_cnt = (text1_trigs & text2_trigs).size
+
+            same_cnt.to_f / all_cnt
+            # rescue StandardError => e
+            #   puts "Error comparing text: #{e.message}"
+          end
+
+          def trigramify(text)
+            trigs = []
+            text.chars.each_cons(3) { |v| trigs << v.join }
+            trigs
+          end
+
+          def clean_amount(transaction)
+            transaction.debit = transaction.clean_amount(transaction.debit)
+            transaction.credit = transaction.clean_amount(transaction.credit)
+          end
+        end
+      end
+    end
+  end
+end