chris_lib 2.2.1 → 2.2.2

data/lib/chris_lib/shell_methods.rb

@@ -1,40 +1,89 @@
-# methods for bash ruby scripts
+# Helpers for shell-friendly Ruby scripts and deployment utilities.
 module ShellMethods
   require 'dotenv'
   require 'bundler'
   require 'optparse'
   Dotenv.load
 
-  # runs an R script from ruby
-  # script_path is absolute path of R script
-  # arg1 is an argument passed to script, can access in R by
-  # arg1 <- commandArgs(trailingOnly=TRUE)[1]
+  # Run an R script via `Rscript --vanilla`
+  #
+  # @param script_path [String] absolute path to the R script
+  # @param arg1 [String] first argument passed to the script (accessible in R via `commandArgs(trailingOnly=TRUE)[1]`)
+  # @return [String] stdout from the R script
+  # @note Warns and returns `nil` when the script is missing.
   def r_runner(script_path, arg1)
-    `Rscript --vanilla #{script_path} #{arg1}`
+    raise ArgumentError, 'script_path must be provided' unless script_path.respond_to?(:to_s)
+    path = script_path.to_s
+    unless File.exist?(path)
+      warn "r_runner: #{path} does not exist"
+      return nil
+    end
+    arg = arg1.to_s
+    `Rscript --vanilla #{path} #{arg}`
   end
 
+  # @param file_path [String]
+  # @return [Integer] file size in bytes
+  # @note Returns 0 and warns when the file is missing.
   def file_size(file_path)
-    `stat -f%z #{file_path}`.to_i
+    raise ArgumentError, 'file_path must be provided' unless file_path.respond_to?(:to_s)
+    path = file_path.to_s
+    unless File.exist?(path)
+      warn "file_size: #{path} does not exist"
+      return 0
+    end
+    `stat -f%z #{path}`.to_i
   end
 
+  # Send an iMessage to the "admin" buddy on macOS.
+  # @param msg [String]
+  # @return [String]
+  # @note Warns and no-ops when `msg` is blank.
   def osx_imessage_admin(msg)
+    if msg.nil? || msg.strip.empty?
+      warn 'osx_imessage_admin called without a message; skipping'
+      return nil
+    end
     `osascript -e 'tell application "Messages" to send "#{msg}" to buddy "admin"'`
   end
 
+  # Trigger a macOS notification via AppleScript.
+  # @param msg [String]
+  # @param title [String]
+  # @return [String]
+  # @note Warns and no-ops when `msg` is blank. Supplies a default title when missing.
   def osx_notification(msg, title)
+    if msg.nil? || msg.strip.empty?
+      warn 'osx_notification called without a message; skipping'
+      return nil
+    end
+    if title.nil? || title.strip.empty?
+      warn 'osx_notification called without a title; using default'
+      title = 'Notification'
+    end
     `osascript -e 'display notification "#{msg}" with title "#{title}"'`
   end
 
+  # @return [String] hostname of the current machine
   def osx_hostname
     `hostname`
   end
 
-  # mail to osx user
-  # https://stackoverflow.com/q/41602984/1299362
+  # Mail the signed-in macOS user using the BSD `mail` command.
+  # @param subject [String]
+  # @param body [String]
+  # @return [String]
+  # @note Warns and no-ops when `subject` is blank.
   def osx_send_mail(subject, body = nil)
+    if subject.nil? || subject.strip.empty?
+      warn 'osx_send_mail called without a subject; skipping'
+      return nil
+    end
     `echo "#{body}" | mail -s "#{subject}" 'Chris'`
   end
 
+  # Parse CLI options for deployment scripts.
+  # @return [Hash] options hash with keys :skip_migration, :fast, :special_rake
   def parse_options
     @options = {}
     OptionParser.new do |opts|
@@ -51,16 +100,22 @@ module ShellMethods
     @options[:skip_migration] = true   if @options[:fast]
   end
 
+  # Placeholder for future custom rake tasks.
+  # @raise [RuntimeError] always, prompting implementers to override
   def run_special_rake_task
     fail 'Need to implement by asking for name of rake task and
     also requiring confirmation'
   end
 
+  # Create a Postgres snapshot by delegating to `script/getSnapShot.sh`.
+  # @return [Boolean] command exit status
   def backup_database
     file_path = "../backups/prod#{time_hash}.dump"
     system('./script/getSnapShot.sh production ' + file_path)
   end
 
+  # Notify users of an impending deploy via Heroku and progress bar countdown.
+  # @return [void]
   def warn_users
     system('heroku run rake util:three_min_warning --remote production')
     # spend one minute precompiling 
@@ -76,6 +131,8 @@ module ShellMethods
     system('heroku run rake util:warn_under_maintenance --remote production')
   end
 
+  # Timestamp helper used to build backup filenames.
+  # @return [String]
   def time_hash
     time = Time.now
     time.day.to_s + time.month.to_s + time.year.to_s + '-' + time.hour.to_s + time.min.to_s
@@ -84,6 +141,9 @@ module ShellMethods
 # change in response to
 #[DEPRECATED] `Bundler.with_clean_env` has been deprecated in favor of `Bundler.with_unbundled_env`. If you instead want the environment before bundler was originally loaded, use `Bundler.with_original_env`
 # remove this comment when clear that this works.
+  # Compare local and remote database schema versions.
+  # @param remote [String, nil] Heroku remote name
+  # @return [Boolean, nil] true when versions match, false when mismatched, nil when versions cannot be read
   def same_db_version(remote: nil)
     destination = (remote.nil? ? nil : "--remote #{remote}")
     lv = `rake db:version`
@@ -102,6 +162,7 @@ module ShellMethods
     l_version == h_version
   end
 
+  # Ensure git workspace is clean before deploying.
   def check_git_clean
     puts "Checking git status"
     gs = `git status`
@@ -110,6 +171,7 @@ module ShellMethods
     exit 1
   end
 
+  # Verify that `chris_lib` is up to date before deploying.
   def check_chris_lib_status
     gs=`cd ../chris_lib;git status`; lr=$?.successful?
     return unless gs['working tree clean'].nil? && gs['up-to-date'].nil?
@@ -118,6 +180,10 @@ module ShellMethods
     system('cd $OLDPWD')
   end
 
+  # Optionally run migrations if local and remote schema versions differ.
+  # @param remote [String, nil]
+  # @param skip_migration [Boolean]
+  # @return [void]
   def migrate_if_necessary(remote: nil, skip_migration: false)
     if skip_migration
       puts "No migration will be performed due to --fast or --skip_migration options"
@@ -137,7 +203,11 @@ module ShellMethods
     end
   end
 
+  # Notify Rollbar of a new deploy via its API.
+  # @param access_token [String, nil]
+  # @return [void]
   def notify_rollbar_of_deploy(access_token: nil)
+    warn 'notify_rollbar_of_deploy called without access token' if access_token.nil? || access_token.empty?
     system("ACCESS_TOKEN=#{access_token}")
     system("ENVIRONMENT=production")
     system("LOCAL_USERNAME=`whoami`")
@@ -158,4 +228,4 @@ module ShellMethods
       puts "Failure to notify Rollbar of deploy of v#{TGM_VERSION} with SHA #{sha[0..5]}", cr
     end
   end
-end
+end

data/lib/chris_lib/test_access.rb

@@ -1,15 +1,30 @@
 module TestAccess
-	# A rspec macro to test access security for controllers, call <tt>it_should_route_to(path,actions)</tt>
-  # where path is a string of the form <tt>url_path</tt> and actions is a hash of symbols
-  # that represent actions to be protected. 
-  # An example call is <tt>it_should_route_to('login_path',:edit,:update)</tt>.  The call is
-  # made in a describe or context block with a preceding <tt>require TestAccess</tt>.
+	# An RSpec helper that verifies protected controller actions redirect to a login path.
   #
+  # Include the module and call {.it_should_route_to} with the protected actions:
+  #
+  #   it_should_route_to('login_path', [:edit, :update])
+  #
+  # Optionally provide a `flash_message` expectation.
+	# @!visibility private
 	module ExampleMethods
 	end
+
+	# @!visibility private
 	module ExampleGroupMethods
+	  # Define a set of expectations that each action redirects to the provided path.
+	  # @param path [String] helper method name that resolves to the desired redirect URL
+	  # @param actions [Array<Symbol>]
+	  # @param flash_message [String, nil] text to match in `flash[:error]`
 	  def it_should_route_to(path,actions,flash_message=nil)
+			raise ArgumentError, 'path must respond to #to_s' unless path.respond_to?(:to_s)
+			actions = Array(actions)
+			if actions.empty?
+				warn 'it_should_route_to called with no actions; nothing to verify'
+				return
+			end
 			actions.each do |a|
+				raise ArgumentError, "action #{a.inspect} must respond to #to_sym" unless a.respond_to?(:to_sym)
 				it "should deny access to #{a}" do
           if Rails::VERSION::MAJOR >= 5
             get a.to_sym, params: { id: 1}
@@ -31,8 +46,12 @@ module TestAccess
 			end
 		end
   end
+  # @!visibility private
   def self.included(receiver)
+    unless receiver.respond_to?(:it)
+      warn 'TestAccess included into an object without RSpec example support'
+    end
     receiver.extend         ExampleGroupMethods
     receiver.send :include, ExampleMethods
   end
-end
+end

data/lib/chris_lib/version.rb

@@ -1,3 +1,3 @@
 module ChrisLib
-  VERSION = '2.2.1'
+  VERSION = '2.2.2'
 end

data/lib/chris_lib.rb

@@ -4,5 +4,8 @@ require "chris_lib/date_ext"
 require "chris_lib/test_access"
 require "chris_lib/chris_math"
 require "chris_lib/shell_methods"
+require "chris_lib/for_chris_lib"
+
+# Main namespace for helpers published by the chris_lib gem.
 module ChrisLib
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: chris_lib
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.2.2
 platform: ruby
 authors:
 - Chris
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-09-17 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dotenv
@@ -39,19 +38,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: minimization
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
@@ -150,6 +177,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: It includes maths, datetime, and rspec access test libraries.
 email:
 - obromios@gmail.com
@@ -162,6 +217,7 @@ files:
 - lib/chris_lib.rb
 - lib/chris_lib/chris_math.rb
 - lib/chris_lib/date_ext.rb
+- lib/chris_lib/for_chris_lib.rb
 - lib/chris_lib/shell_methods.rb
 - lib/chris_lib/test_access.rb
 - lib/chris_lib/version.rb
@@ -172,7 +228,6 @@ licenses:
 metadata:
   source_code_uri: https://github.com/obromios/chris_lib
   changelog_uri: https://github.com/obromios/chris_lib/blob/master/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -187,8 +242,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key:
+rubygems_version: 3.7.2
 specification_version: 4
 summary: This an eclectic collection of methods. It include maths, datetime, and rspec
   access test libraries.