ocfl-tools 0.9.14 → 0.9.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 915f99359028f587423cb4125cc197215fd2d6f0ae3a663c2d421ba2fa636d04
-  data.tar.gz: 7aaa9773441a5a672b9a94852946cdb7819d6aecc58ee176995b1cfd64ea8173
+  metadata.gz: 817dfd488b3cb6f05522175c68cba6385c76007950dc03af3162579517a1a653
+  data.tar.gz: 402eb44681f151b91e1403ed5fa289c632f62480c1f3199f7e8f468ca6f4e567
 SHA512:
-  metadata.gz: b06efb97d5cb2dc0a0376310ffefb66c93bce411a932de1afe7f49f4ee200f774c9d6465c424207cc390c35804151b03e9b370b8ca4397fb44b161d0cf9aee40
-  data.tar.gz: b29499a9bcbba6cb3dedfc140d6208a42ad712af0d70a1fd4b96802f4f58bc2f02532b97bb7d63138e3a93b17005939de6ed6ffe909545fe452f2b4e5e30fc0e
+  metadata.gz: a8a98f2d7bfab21babf2103857d970ad8d8e6e2cb1b6131b39f654568f161055ab4b4c567c2360d0d772bf709bb791d8125df0eff161de07eafec04d1c2fdffa
+  data.tar.gz: a8e692758b075775d124939bb533761b56f03b5b5d79a2ed3f916105f61b2361c1cd024f49886d554fd2578ac7e768c155c703ff85238b399a6b204047782476

data/VERSION

@@ -1 +1 @@
-0.9.14
+0.9.15

data/lib/ocfl_tools/ocfl_errors.rb

@@ -1,21 +1,71 @@
 module OcflTools
   module Errors
+    # See this for a nice model.
+    # https://github.com/ryanb/cancan/blob/master/lib/cancan/exceptions.rb
+    class ValidationError < StandardError
+      attr_accessor :details
+      attr_accessor :msg
+      def initialize(msg: "A validation error has occured.", details: {} )
+        @msg = msg
+        @details = details
+      end
+    end
+
+    # For bad client requests
+    class ClientError < StandardError; end
+
+    class SyntaxError < StandardError
+      def initialize(msg="Generic syntax error.")
+      end
+    end
+
+    class UnableToLoadInventoryFile < StandardError
+      def initialize(msg="Requested inventory file failed to load. See downstream errors for details.")
+      end
+    end
+
+    ### Client errors (you asked for the wrong stuff)
+    class RequestedKeyNotFound < ClientError
+      # You ask for key 'foo', but you are dumb and key 'foo' is not in the spec.
+      def initialize(msg="Requested key not found in provided inventory.json.")
+      end
+    end
+
+    class RequestedFileNotFound < ClientError
+      def initialize(msg="Requested file does not exist.")
+      end
+    end
+
+    class RequestedDirectoryNotFound < ClientError
+      def initialize(msg="Requested directory does not exist.")
+      end
+    end
+
+    class FileMissingFromVersionState < ClientError
+      def initialize(msg="The requested file cannot be found in the provided version state block.")
+      end
+    end
+
+    class FileDigestMismatch < ClientError
+      def initialize(msg="The requested file already exists in inventory with different digest.")
+      end
+    end
 
-    class Error211 < StandardError
-      def initialize(msg="inventory.json is not valid JSON.")
-        super
+    # You asked for version -1, or version 44c.
+    class NonCompliantValue < ClientError
+      def initialize(msg="Value provided is outside of specification bounds.")
       end
     end
 
-    class Error216 < StandardError
-      def initialize(msg="Unable to find required key in inventory.json.")
-        super
+    ### Validation errors (stuff that MUST be true, per spec, is not)
+    class RequiredKeyNotFound < ValidationError
+      # key 'foo' is in the spec and should be in the inventory. Fail if not.
+      def initialize(msg="Required key not found in provided inventory.json.")
       end
     end
 
-    class Error217 < StandardError
-      def initialize(msg="Required key in inventory.json must contain a value.")
-        super
+    class CannotEditPreviousVersion < ValidationError
+      def initialize(msg="Previous version state blocks are considered read-only.")
       end
     end
 

data/lib/ocfl_tools/ocfl_inventory.rb

@@ -54,9 +54,13 @@ module OcflTools
       begin
         JSON.parse(File.read(file))
       rescue JSON::ParserError
-        raise OcflTools::Errors::Error211
-      rescue StandardError
-        raise "An unknown error occured reading file #{file}" # catch/encapsulate any JSON::Parser or FileIO issues
+        raise OcflTools::Errors::ValidationError, details: { "E211" => ["#{file} is not valid JSON."] }
+      rescue Errno::ENOENT
+        # raise OcflTools::Errors::Error215, "expected inventory file #{file} not found!"
+        raise OcflTools::Errors::ValidationError, details: { "E215" => ["expected inventory file #{file} not found!"] }
+      # rescue Errno::EACCES Don't think we need to explicitly raise file permissions; let StdErr take it.
+      rescue StandardError => e
+        raise "An unknown error occured reading file #{file}: #{e}" # catch/encapsulate any FileIO issues
       end
     end
 
@@ -67,22 +71,31 @@ module OcflTools
       import_hash = read_json(file)
 
       # REQUIRED keys; raise exception if not found.
+      e216_errors = []
+      e217_errors = []
+      error_hash  = {}
       [ 'id', 'head', 'type', 'digestAlgorithm', 'manifest', 'versions' ].each do | key |
         unless import_hash.key?(key)
-          raise OcflTools::Errors::Error216, "Required key #{key} not found"
+          e216_errors << "Required key #{key} not found in #{file}"
+          error_hash["E216"] = e216_errors # we'll keep updating this value as new errors are recorded.
         end
-        if import_hash[key].empty?
-          raise OcflTools::Errors::Error217, "Required key #{key} must contain a value"
+        if import_hash.key?(key) && import_hash[key].empty?
+          # If the key exists but it's empty, that's also a problem!
+          e217_errors << "Required key #{key} in #{file} must contain a value"
+          error_hash["E217"] = e217_errors
         end
       end
+      # Raise a problem if we have anything in error_hash.
+      if error_hash.size > 0
+        raise OcflTools::Errors::ValidationError, details: error_hash
+      end
+
+      # The actual values of these keys may be hot garbage, but it's not ocfl_inventory's place to check.
 
       @id               = import_hash['id']
       @head             = import_hash['head']
       @type             = import_hash['type']
       @digestAlgorithm  = import_hash['digestAlgorithm']
-#      if import_hash.key?('contentDirectory')
-#        @contentDirectory = import_hash['contentDirectory']
-#      end
       @manifest         = import_hash['manifest']
       @versions         = import_hash['versions']
       # Optional keys - contentDirectory and fixity block.

data/lib/ocfl_tools/ocfl_object.rb

@@ -52,7 +52,7 @@ module OcflTools
     # @note will raise an exception if you attempt to query a non-existent version.
     def set_version_message(version, message)
       unless @versions.key?(OcflTools::Utils.version_int_to_string(version))
-        raise "Version #{version} does not yet exist!"
+        raise OcflTools::Errors::RequestedKeyNotFound, "Version #{version} does not yet exist!"
       end
 
       @versions[OcflTools::Utils.version_int_to_string(version)]['message'] = message
@@ -64,7 +64,7 @@ module OcflTools
     # @note will raise an exception if you attempt to query a non-existent version.
     def get_version_message(version)
       unless @versions.key?(OcflTools::Utils.version_int_to_string(version))
-        raise "Version #{version} does not yet exist!"
+        raise OcflTools::Errors::RequestedKeyNotFound, "Version #{version} does not yet exist!"
       end
 
       @versions[OcflTools::Utils.version_int_to_string(version)]['message']
@@ -76,7 +76,7 @@ module OcflTools
     # @note will raise an exception if you attempt to query a non-existent version.
     def set_version_created(version, created)
       unless @versions.key?(OcflTools::Utils.version_int_to_string(version))
-        raise "Version #{version} does not yet exist!"
+        raise OcflTools::Errors::RequestedKeyNotFound, "Version #{version} does not yet exist!"
       end
 
       @versions[OcflTools::Utils.version_int_to_string(version)]['created'] = created
@@ -88,7 +88,7 @@ module OcflTools
     # @note will raise an exception if you attempt to query a non-existent version.
     def get_version_created(version)
       unless @versions.key?(OcflTools::Utils.version_int_to_string(version))
-        raise "Version #{version} does not yet exist!"
+        raise OcflTools::Errors::RequestedKeyNotFound, "Version #{version} does not yet exist!"
       end
 
       @versions[OcflTools::Utils.version_int_to_string(version)]['created']
@@ -100,7 +100,7 @@ module OcflTools
     # @note will raise an exception if you attempt to query a nonexistent version.
     def set_version_user(version, user)
       unless @versions.key?(OcflTools::Utils.version_int_to_string(version))
-        raise "Version #{version} does not yet exist!"
+        raise OcflTools::Errors::RequestedKeyNotFound, "Version #{version} does not yet exist!"
       end
 
       @versions[OcflTools::Utils.version_int_to_string(version)]['user'] = user
@@ -112,7 +112,7 @@ module OcflTools
     # @note will raise an exception if you attempt to query a nonexistent version.
     def get_version_user(version)
       unless @versions.key?(OcflTools::Utils.version_int_to_string(version))
-        raise "Version #{version} does not yet exist!"
+        raise OcflTools::Errors::RequestedKeyNotFound, "Version #{version} does not yet exist!"
       end
 
       @versions[OcflTools::Utils.version_int_to_string(version)]['user']
@@ -184,7 +184,7 @@ module OcflTools
       my_state = get_state(version)
 
       unless version == version_id_list.max
-        raise "Can't edit prior versions! Only version #{version_id_list.max} can be modified now."
+        raise OcflTools::Errors::CannotEditPreviousVersion, "Can't edit prior versions! Only version #{version_id_list.max} can be modified now."
       end
 
       # if the key is not in the manifest, assume that we meant to add it.
@@ -205,7 +205,7 @@ module OcflTools
       # If so; fail. We don't do implicit / soft adds. You want that, be explict: do an update_file instead.
       existing_files = get_files(version)
       if existing_files.key?(file)
-        raise 'File already exists with different digest in this version! Consider update instead.'
+        raise OcflTools::Errors::FileDigestMismatch, "#{file} already exists with different digest in version #{version}. Consider update instead."
       end
 
       # if it's not in State already, just add it.
@@ -256,7 +256,7 @@ module OcflTools
       # Does Digest exist in @manifest? Fail if not.
       # Doe fixityAlgorithm exist as a key in @fixity? Add if not.
       unless @manifest.key?(digest) == true
-        raise "Unable to find digest #{digest} in manifest!"
+        raise OcflTools::Errors::RequestedKeyNotFound, "Unable to find digest #{digest} in manifest!"
       end
 
       filepaths = @manifest[digest]
@@ -289,7 +289,7 @@ module OcflTools
       my_state = get_state(version) # Creates version & copies state from prior version if doesn't exist.
 
       unless version == version_id_list.max
-        raise "Can't edit prior versions! Only version #{version} can be modified now."
+        raise OcflTools::Errors::CannotEditPreviousVersion, "Can't edit prior versions! Only version #{version_id_list.max} can be modified now."
       end
 
       my_digest = get_digest(file, version)
@@ -364,7 +364,7 @@ module OcflTools
       end
       # Now see if the requested file is actually here.
       unless my_files.key?(file)
-        raise "Get_digest can't find requested file in given version!"
+        raise OcflTools::Errors::FileMissingFromVersionState, "Get_digest can't find requested file #{file} in version #{version}."
       end
 
       my_files[file]
@@ -377,7 +377,7 @@ module OcflTools
     # @note If a (n-1) version exists in the object, and the requested version does not yet exist, this method will copy that version's state block into the new version.
     def get_version(version)
       unless version > 0
-        raise "OCFL object version cannot be zero!"
+        raise OcflTools::Errors::NonCompliantValue, "Requested value '#{version}' for object version does not comply with specification."
       end
       if @versions.key?(OcflTools::Utils.version_int_to_string(version))
         @versions[OcflTools::Utils.version_int_to_string(version)]
@@ -414,11 +414,15 @@ module OcflTools
     # @param [Hash] hash use this hash for the content of the new OCFL version block.
     def set_version(version, hash)
       # SAN Check to make sure passed Hash has all expected keys.
+      e216_errors = []
       %w[created message user state].each do |key|
         if hash.key?(key) == false
-          raise "version #{version} hash block is missing required #{key} key"
+          e216_errors << "version #{version} hash block is missing required #{key} key."
         end
       end
+      if e216_errors.size > 0
+        raise OcflTools::Errors::ValidationError, details: { "E216" => e216_errors }
+      end
       @versions[OcflTools::Utils.version_int_to_string(version)] = hash
     end
   end

data/lib/ocfl_tools/ocfl_validator.rb

@@ -63,7 +63,14 @@ module OcflTools
     # @return {OcflTools::OcflResults} of event results
     def verify_fixity(inventory_file: "#{@ocfl_object_root}/inventory.json", digest: 'md5')
       # Gets the appropriate fixity block, calls compare_hash_checksums
-      @inventory = OcflTools::OcflInventory.new.from_file(inventory_file)
+
+      begin
+        @inventory = load_inventory(inventory_file)
+      rescue OcflTools::Errors::ValidationError
+        @my_results.error('E210', 'verify_fixity', "Unable to process inventory file #{inventory_file}.")
+        return @my_results
+      end
+
       # Since fixity blocks are not required to be complete, we just validate what's there.
       # So get the fixity block, flip it, expand it, checksum it against the same files on disk.
 
@@ -121,9 +128,9 @@ module OcflTools
         return @my_results
       end
 
-      if load_inventory(inventory_file) == true
-        @inventory         = OcflTools::OcflInventory.new.from_file(inventory_file)
-      else
+      begin
+        @inventory = load_inventory(inventory_file)
+      rescue OcflTools::Errors::ValidationError
         @my_results.error('E210', 'verify_fixity', "Unable to process inventory file #{inventory_file}.")
         return @my_results
       end
@@ -260,9 +267,9 @@ module OcflTools
         return @my_results
       end
 
-      if load_inventory(inventory_file) == true
-        @inventory = OcflTools::OcflInventory.new.from_file(inventory_file)
-      else
+      begin
+        @inventory = load_inventory(inventory_file)
+      rescue OcflTools::Errors::ValidationError
         @my_results.error('E210', 'verify_checksums', "Unable to process inventory file #{inventory_file}.")
         return @my_results
       end
@@ -312,7 +319,8 @@ module OcflTools
       # 1. use get_version_format to determine the format used for version directories.
       #    If we can't deduce it by inspection of the object_root, ERROR and try and process using site-wide defaults.
       if get_version_format == false
-        error = true
+        @my_results.error('E111', 'verify_structure', 'OCFL unable to determine version format by inspection of directories.')
+        @error = true
       end
 
       object_root_dirs  = []
@@ -339,12 +347,13 @@ module OcflTools
       # 2b. What's the highest version we should find here?
       # 2c. What should our contentDirectory value be?
       if File.exist? "#{@ocfl_object_root}/inventory.json"
-        if load_inventory("#{@ocfl_object_root}/inventory.json") == true
+        begin
+          @inventory = load_inventory("#{@ocfl_object_root}/inventory.json")
           json_digest      = OcflTools::Utils::Inventory.get_digestAlgorithm("#{@ocfl_object_root}/inventory.json")
           contentDirectory = OcflTools::Utils::Inventory.get_contentDirectory("#{@ocfl_object_root}/inventory.json")
           expect_head      = OcflTools::Utils::Inventory.get_value("#{@ocfl_object_root}/inventory.json", 'head')
           file_checks << "inventory.json.#{json_digest}"
-        else
+        rescue OcflTools::Errors::ValidationError
           # We couldn't load up the inventory; use site defaults.
           contentDirectory = OcflTools.config.content_directory
           json_digest      = OcflTools.config.digest_algorithm
@@ -444,7 +453,17 @@ module OcflTools
         object_root_dirs.delete('extensions')
       end
 
-      version_directories = OcflTools::Utils::Files.get_version_directories(@ocfl_object_root)
+      begin
+        version_directories = OcflTools::Utils::Files.get_version_directories(@ocfl_object_root)
+      rescue OcflTools::Errors::ValidationError => e
+        e.details.each do | code, messages |
+          messages.each do | msg |
+            @my_results.error(code, 'verify_structure', msg)
+          end
+        end
+        # If we actually throw a validation error, we can't proceed: no version directories found!
+        return @my_results
+      end
 
       remaining_dirs = object_root_dirs - version_directories
 
@@ -466,7 +485,7 @@ module OcflTools
         # just that they're valid version dir names, sorted in ascending order, and they exist.
         if version_directories.include? expected_directory
           # Could verbose log this here.
-          # @my_results.ok('O200', 'verify_sructure', "Expected version directory #{expected_directory} found.")
+          # @my_results.info('I200', 'verify_sructure', "Expected version directory #{expected_directory} found.")
         else
           @my_results.error('E013', 'verify_structure', "Expected version directory #{expected_directory} missing from directory list #{version_directories} ")
           error = true
@@ -499,7 +518,8 @@ module OcflTools
         # 9. Warn if inventory.json and sidecar are not present in version directory.
         file_checks = []
         if File.exist? "#{@ocfl_object_root}/#{ver}/inventory.json"
-          if load_inventory("#{@ocfl_object_root}/inventory.json") == true
+          begin
+            @inventory = load_inventory("#{@ocfl_object_root}/#{ver}/inventory.json")
             json_digest      = OcflTools::Utils::Inventory.get_digestAlgorithm("#{@ocfl_object_root}/#{ver}/inventory.json")
             file_checks << 'inventory.json'
             file_checks << "inventory.json.#{json_digest}"
@@ -508,12 +528,14 @@ module OcflTools
               @my_results.error('E111', 'verify_structure', "contentDirectory value #{versionContentDirectory} in version #{ver} does not match expected contentDirectory value #{contentDirectory}.")
               error = true
             end
-          else
+          rescue OcflTools::Errors::ValidationError
+            # We couldn't load up the inventory; use site defaults.
+            # We should also record the error in @my_results?
             json_digest = OcflTools.config.digest_algorithm
             file_checks << 'inventory.json'
             file_checks << "inventory.json.#{json_digest}"
+            error = true
           end
-
         else
           file_checks << 'inventory.json'         # We look for it, even though we know we won't find it, so we can log the omission.
           file_checks << 'inventory.json.sha512'  # We look for it, even though we know we won't find it, so we can log the omission.
@@ -557,12 +579,6 @@ module OcflTools
         # 11. WARN if a contentDirectory exists, but is empty.
         if version_dirs.include? contentDirectory
           version_dirs.delete(contentDirectory)
-#          if Dir.empty?(contentDirectory)
-#            @my_results.warn('W102', 'verify_structure', "OCFL 3.3.1 version #{ver} contentDirectory should not be empty.")
-#          end
-#        else
-#          # Informational message that contentDir does not exist. Not necssarily a problem!
-#          @my_results.info('I101', 'verify_structure', "OCFL 3.3.1 version #{ver} does not contain a contentDirectory.")
         end
 
         # 12. Warn if any directories other than the expected 'content' directory are found in the version directory.
@@ -587,11 +603,8 @@ module OcflTools
     # @return {OcflTools::OcflResults} of verify events
     def verify_directory(version)
       # start by getting version format and directories.
-      if @version_format.nil?
-        @version_format = OcflTools::Utils::Files.get_version_format(@ocfl_object_root)
-      end
+      get_version_format # sets @version_format, one way or another.
 
-      # result = OcflTools.config.version_format % version.to_i
       version_name = @version_format % version.to_i
       # Make sure this directory actually exists.
       unless File.directory?("#{@ocfl_object_root}/#{version_name}")
@@ -653,44 +666,38 @@ module OcflTools
     def verify_inventory(inventory_file = "#{@ocfl_object_root}/inventory.json")
       # Load up the object with ocfl_inventory, push it through ocfl_verify.
       @my_results ||= OcflTools::OcflResults.new
-      # Inventory file does not exist; create a results object, record this epic fail, and return.
-      if File.exist?(inventory_file)
-        if load_inventory("#{@ocfl_object_root}/inventory.json") == true
-          @inventory = OcflTools::OcflInventory.new.from_file(inventory_file)
-          @verify    = OcflTools::OcflVerify.new(@inventory)
-          @verify.check_all # creates & returns @results object from OcflVerify
-        else
-          # The inventory had problems; we can't run verify.
-          @my_results.error('E210', 'verify_inventory', "Unable to process inventory file #{inventory_file}.")
-          return @my_results
-        end
-      else
-        @my_results.error('E215', 'verify_inventory', "Expected inventory file #{inventory_file} not found.")
+      # If inventory_file does not exist, load_inventory will throw and log an E215.
+      begin
+        @inventory = load_inventory(inventory_file)
+        @inventory = OcflTools::OcflInventory.new.from_file(inventory_file)
+        @verify    = OcflTools::OcflVerify.new(@inventory)
+        @verify.check_all # creates & returns @results object from OcflVerify
+      # This could be OcflTools::Errors::ValidationError now.
+      rescue OcflTools::Errors::ValidationError
+        # I don't think we need to throw this E210 any more.
+        @my_results.error('E210', 'verify_inventory', "Unable to process inventory file #{inventory_file}.")
         return @my_results
       end
     end
 
   private
     # load up an inventory file and handle any errors.
-    # Returns true if the inventory file is syntatically correct; false if otherwise.
+    # Returns an inventory file is syntatically correct; false if otherwise.
     def load_inventory(inventory_file)
-      begin
-        @my_results ||= OcflTools::OcflResults.new
-        OcflTools::OcflInventory.new.from_file(inventory_file)
-        return true
-      rescue RuntimeError
-        @my_results.error('E210', 'load_inventory', "Unable to read Inventory file #{inventory_file}")
-        return false
-      rescue OcflTools::Errors::Error211
-        @my_results.error('E211', 'load_inventory', "#{inventory_file} is not valid JSON.")
-        return false
-      rescue OcflTools::Errors::Error216 => e
-        @my_results.error('E216', 'load_inventory', "#{e} in #{inventory_file}")
-        return false
-      rescue OcflTools::Errors::Error217 => e
-        @my_results.error('E217', 'load_inventory', "#{e} in #{inventory_file}")
-        return false
-      end
+      @my_results ||= OcflTools::OcflResults.new
+      OcflTools::OcflInventory.new.from_file(inventory_file)
+      # The generic 'something went wrong but I don't know what'; not sure if we should keep this.
+      rescue RuntimeError => e
+        @my_results.error('E210', 'load_inventory', "#{e}")
+        raise
+      rescue OcflTools::Errors::ValidationError => e
+        e.details.each do | code, messages |
+          # code is a string, messages is an array.
+          messages.each do | msg |
+            @my_results.error(code, 'load_inventory', msg)
+          end
+        end
+        raise # re-raise the error.
     end
 
     # Compares the state blocks for all versions across all inventories in the object,
@@ -784,13 +791,22 @@ module OcflTools
 
     def get_version_format
       begin
+        @my_results ||= OcflTools::OcflResults.new
         @version_format ||= OcflTools::Utils::Files.get_version_format(@ocfl_object_root)
         @my_results.ok('O111', 'version_format', 'OCFL conforming first version directory found.')
-        return true
-      rescue StandardError
+        return @version_format
+      rescue OcflTools::Errors::ValidationError => e
+        # OcflTools::Utils::Files.get_version_format doesn't set errors, so capture them here.
+        e.details.each do | code, messages |
+          # code is a string, messages is an array.
+          messages.each do | msg |
+            @my_results.error(code, 'load_inventory', msg)
+          end
+        end
+        # Add on another error explaining how we got here.
         @my_results.error('E111', 'version_format', 'OCFL unable to determine version format by inspection of directories.')
-        @version_format = OcflTools.config.version_format
         @my_results.warn('W111', 'version_format', "Attempting to process using default value: #{OcflTools.config.version_format}")
+        @version_format = OcflTools.config.version_format
         return false
       end
     end

data/lib/ocfl_tools/utils_file.rb

@@ -52,7 +52,8 @@ module OcflTools
       # Given an object root directory, deduce and return the version directories by inspecting disk.
       def self.get_version_directories(object_root_dir)
         unless Dir.exist?(object_root_dir) == true
-          raise 'Directory does not exist!'
+          # This is a client error.
+          raise OcflTools::Errors::RequestedDirectoryNotFound, "#{object_root_dir} does not exist!"
         end
 
         object_root_dirs = []
@@ -62,7 +63,8 @@ module OcflTools
           object_root_dirs << file if File.directory? file
         end
         if object_root_dirs.empty?
-          raise "No directories found in #{object_root_dir}!"
+          # This is a validation error.
+          raise OcflTools::Errors::ValidationError, details: { "E100" => ["#{object_root_dir} is empty!"] }
         end
 
         # Needs to call get version_format method here.
@@ -71,15 +73,18 @@ module OcflTools
             version_directories << i
           end
         end
-        raise 'No version directories found!' if version_directories.empty?
-
+        # This is a validation error; we expect to find matching version directories.
+        if version_directories.empty?
+          raise OcflTools::Errors::ValidationError, details: { "E013" => ["#{object_root_dir} must contain at least one identifiable version directory."] }
+        end
         version_directories.sort! # sort it, to be nice.
       end
 
       # Given an object_root_directory, deduce the format used to describe version directories.
       def self.get_version_format(object_root_dir)
         unless Dir.exist?(object_root_dir) == true
-          raise 'Directory does not exist!'
+          # This is a client error.
+          raise OcflTools::Errors::RequestedDirectoryNotFound, "#{object_root_dir} does not exist!"
         end
 
         # Get all directories starting with 'v', sort them.
@@ -98,14 +103,16 @@ module OcflTools
         first_version.slice!(0, 1) # cut the leading 'v' from the string.
         if first_version.length == 1 # A length of 1 for the first version implies 'v1'
           unless first_version.to_i == 1
-            raise "#{object_root_dir}/#{first_version} is not the first version directory!"
+            # This is a validation error; there must be a v1 directory.
+            # E015 "OCFL 3.5.3 Expected version sequence not found. Expected version #{count}, found version #{my_versions[count]}."
+            raise OcflTools::Errors::ValidationError, details: { "E015" => ["Expected version 1 not found. Found version #{first_version.to_i} instead."] }
           end
 
           version_format = 'v%d'
         else
           # Make sure this is Integer 1.
           unless first_version.to_i == 1
-            raise "#{object_root_dir}/#{first_version} is not the first version directory!"
+            raise OcflTools::Errors::ValidationError, details: { "E015" => ["Expected version 1 not found. Found version #{first_version.to_i} instead."] }
           end
 
           version_format = "v%0#{first_version.length}d"
@@ -170,24 +177,34 @@ module OcflTools
         # g_v_d returns a sorted array already. Reverse it, so we start with highest version.
         my_versions = OcflTools::Utils::Files.get_version_directories(object_root_dir).reverse
         case
+        # Return the inventory file in the highest version dir, if it exists.
         when File.exist?("#{object_root_dir}/#{my_versions[0]}/inventory.json")
           return "#{object_root_dir}/#{my_versions[0]}/inventory.json"
+        # Otherwise, return the inventory file in the root, if it exists.
         when File.exist?("#{object_root_dir}/inventory.json")
           return "#{object_root_dir}/inventory.json"
         else
-          # Quit out here if there was only 1 version directory
+          # We don't have a highest-version inventory, and we don't have a root inventory.
+          # This is a problem! But there might be an inventory file in a non-highest-version dir.
+          # Quit out here if there was only 1 version directory (We've already checked this)
           unless my_versions.size > 1
-            raise "No inventory file found in #{object_root_dir}!"
+            # This is a validation error; no inventory files found.
+            raise OcflTools::Errors::ValidationError, details: { "E215" => ["OCFL 3.1 Expected inventory file not found in #{object_root_dir} or discovered version directories."] }
           end
 
-          my_versions.delete_at(0) # drop the first element.
+          my_versions.delete_at(0) # drop the first element (we've already checked it).
           my_versions.each do |v|
+            # Return the highest version inventory file we find.
+            # Note, this is technically a non-compliant object root, but we
+            # want to return a result if we have one - we might be attempting object
+            # recovery and something is better than nothing.
             if File.exist?("#{object_root_dir}/#{v}/inventory.json")
               return "#{object_root_dir}/#{v}/inventory.json"
             end
           end
-          # If we get here, no inventory file found!
-          raise "No inventory file found in #{object_root_dir}!"
+          # If we get here, no inventory file found in any version dirs or the object root.
+          # This is a validation error.
+          raise OcflTools::Errors::ValidationError, details: { "E215" => ["OCFL 3.1 Expected inventory file not found in #{object_root_dir} or discovered version directories."] }
         end
       end
     end

data/lib/ocfl_tools/utils_inventory.rb

@@ -12,7 +12,7 @@ module OcflTools
       # @return [String or nil] the value of the requested key, or nil if not found.
       def self.get_value(inventory_file, key)
         unless %w[contentDirectory digestAlgorithm head type id].include?(key)
-          raise "#{key} is not a valid OCFL inventory header key"
+          raise OcflTools::Errors::RequestedKeyNotFound, "#{key} is not a valid OCFL inventory header key"
         end
 
         inventory = OcflTools::OcflInventory.new.from_file(inventory_file)

data/ocfl-tools.gemspec

@@ -8,10 +8,10 @@ Gem::Specification.new do |gem|
   gem.homepage      = 'https://github.com/sul-dlss-labs/OCFL-Tools'
   gem.licenses      = ['Apache-2.0']
 
+  # Don't include fixtures in the gem.
   gem.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
-  # gem.files         = `git ls-files`.split($OUTPUT_RECORD_SEPARATOR)
 
   gem.add_runtime_dependency 'anyway_config', '~> 1.0'
   gem.add_runtime_dependency 'fileutils', '~> 1.3'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ocfl-tools
 version: !ruby/object:Gem::Version
-  version: 0.9.14
+  version: 0.9.15
 platform: ruby
 authors:
 - Julian M. Morley
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-03-18 00:00:00.000000000 Z
+date: 2020-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: anyway_config
@@ -42,22 +42,22 @@ dependencies:
   name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.2.0
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 2.2.0
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.2.0
 - !ruby/object:Gem::Dependency
   name: pry-byebug
   requirement: !ruby/object:Gem::Requirement
@@ -183,7 +183,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Tools to create, manipulate and write Oxford Common File Layout (OCFL) preservation