berkeley_library-alma 0.0.1

data/.rubocop.yml

@@ -0,0 +1,334 @@
+inherit_mode:
+  merge:
+    - Exclude
+    - Include
+
+# Allow one line around block body (Layout/EmptyLines will still disallow two or more)
+Layout/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+# Allow one line around class body (Layout/EmptyLines will still disallow two or more)
+Layout/EmptyLinesAroundClassBody:
+  Enabled: false
+
+# Allow one line around module body (Layout/EmptyLines will still disallow two or more)
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+# Reasonable line-length check; it's too easy for the cure to be worse than the disease
+Layout/LineLength:
+  Max: 150
+
+# Make indents consistent regardless of the lengths of variables and method names and whatnot
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+# Produces monsters
+Layout/MultilineOperationIndentation:
+  Enabled: false
+
+# We meant to do that
+Naming/MemoizedInstanceVariableName:
+  Enabled: False
+
+# It works in context, trust us
+Naming/MethodParameterName:
+  Enabled: False
+
+# Confusing and weird
+Naming/VariableNumber:
+  Enabled: False
+
+# Do what's readable in the context you're in
+Style/AccessModifierDeclarations:
+  Enabled: false
+
+# 👎 to cultural imperialism
+Style/AsciiComments:
+  Enabled: false
+
+# Seriously?
+Style/CommentedKeyword:
+  Enabled: False
+
+# Disable problematic module documentation check (see https://github.com/bbatsov/rubocop/issues/947)
+Style/Documentation:
+  Enabled: false
+
+# Adding more line noise to format strings will not improve them
+Style/FormatStringToken:
+  Enabled: false
+
+# Putting '# frozen_string_literal: true' everywhere does not make the world a better place
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+# Requiring the lambda() method just makes wordy calls wordier
+Style/Lambda:
+  EnforcedStyle: literal
+
+# `foo.positive?` is cute, but it's not actually more readable than `foo > 0`
+Style/NumericPredicate:
+  Enabled: false
+
+# Unclear why it's a good idea to give parameters semantically meaningless names
+Style/SingleLineBlockParams:
+  Enabled: false
+
+# The semantics of `foo&.bar` are a lot less interchangeable with `foo && foo.bar` than RuboCop thinks
+Style/SafeNavigation:
+  Enabled: false
+
+# Short arrays are often more readable as plain arrays
+Style/WordArray:
+  MinSize: 3
+
+############################################################
+# Added in RuboCop 0.80
+
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.81
+
+Lint/StructNewOverride:
+  Enabled: true
+
+Lint/RaiseException:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.82
+
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+
+Style/ExponentialNotation:
+  Enabled: false
+
+############################################################
+# Added in RuboCop 0.83
+
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+
+Style/SlicingWithRange:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.84
+
+Lint/DeprecatedOpenSSLConstant:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.85
+
+Lint/MixedRegexpCaptureTypes:
+  Enabled: true
+
+Style/RedundantRegexpEscape:
+  Enabled: true
+
+Style/RedundantRegexpCharacterClass:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.86
+
+Style/RedundantFetchBlock:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.87
+
+# Sometimes we separate things for a reason
+Style/AccessorGrouping:
+  Enabled: false
+
+Style/BisectedAttrAccessor:
+  Enabled: true
+
+Style/RedundantAssignment:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.88
+
+Lint/DuplicateElsifCondition:
+  Enabled: true
+
+Style/ArrayCoercion:
+  Enabled: true
+
+Style/CaseLikeIf:
+  Enabled: true
+
+Style/HashAsLastArrayItem:
+  Enabled: true
+
+Style/HashLikeCase:
+  Enabled: true
+
+Style/RedundantFileExtensionInRequire:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.89
+
+Lint/BinaryOperatorWithIdenticalOperands:
+  Enabled: true
+
+Lint/DuplicateRescueException:
+  Enabled: true
+
+Lint/EmptyConditionalBody:
+  Enabled: true
+
+Lint/FloatComparison:
+  Enabled: true
+
+Lint/MissingSuper:
+  Enabled: true
+
+Lint/OutOfRangeRegexpRef:
+  Enabled: true
+
+Lint/SelfAssignment:
+  Enabled: true
+
+Lint/TopLevelReturnWithArgument:
+  Enabled: true
+
+Lint/UnreachableLoop:
+  Enabled: true
+
+Style/ExplicitBlockArgument:
+  Enabled: true
+
+Style/GlobalStdStream:
+  Enabled: true
+
+Style/OptionalBooleanParameter:
+  Enabled: true
+
+Style/SingleArgumentDig:
+  Enabled: true
+
+Style/SoleNestedConditional:
+  Enabled: true
+
+Style/StringConcatenation:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.90
+
+Lint/DuplicateRequire:
+  Enabled: true
+
+Lint/EmptyFile:
+  Enabled: true
+
+Lint/TrailingCommaInAttributeDeclaration:
+  Enabled: true
+
+Lint/UselessMethodDefinition:
+  Enabled: true
+
+Style/CombinableLoops:
+  Enabled: true
+
+Style/KeywordParametersOrder:
+  Enabled: true
+
+Style/RedundantSelfAssignment:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.91
+
+Layout/BeginEndAlignment:
+  Enabled: true
+
+Lint/ConstantDefinitionInBlock:
+  Enabled: true
+
+Lint/IdentityComparison:
+  Enabled: true
+
+Lint/UselessTimes:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 1.1–1.9
+
+Layout/SpaceBeforeBrackets: # (new in 1.7)
+  Enabled: true
+Lint/AmbiguousAssignment: # (new in 1.7)
+  Enabled: true
+Lint/DeprecatedConstants: # (new in 1.8)
+  Enabled: true
+Lint/DuplicateBranch: # (new in 1.3)
+  Enabled: true
+Lint/DuplicateRegexpCharacterClassElement: # (new in 1.1)
+  Enabled: true
+Lint/EmptyBlock: # (new in 1.1)
+  Enabled: true
+Lint/EmptyClass: # (new in 1.3)
+  Enabled: true
+Lint/LambdaWithoutLiteralBlock: # (new in 1.8)
+  Enabled: true
+Lint/NoReturnInBeginEndBlocks: # (new in 1.2)
+  Enabled: true
+Lint/NumberedParameterAssignment: # (new in 1.9)
+  Enabled: true
+Lint/OrAssignmentToConstant: # (new in 1.9)
+  Enabled: true
+Lint/RedundantDirGlobSort: # (new in 1.8)
+  Enabled: true
+Lint/SymbolConversion: # (new in 1.9)
+  Enabled: true
+Lint/ToEnumArguments: # (new in 1.1)
+  Enabled: true
+Lint/TripleQuotes: # (new in 1.9)
+  Enabled: true
+Lint/UnexpectedBlockArity: # (new in 1.5)
+  Enabled: true
+Lint/UnmodifiedReduceAccumulator: # (new in 1.1)
+  Enabled: true
+Style/ArgumentsForwarding: # (new in 1.1)
+  Enabled: true
+Style/CollectionCompact: # (new in 1.2)
+  Enabled: true
+Style/DocumentDynamicEvalDefinition: # (new in 1.1)
+  Enabled: true
+Style/EndlessMethod: # (new in 1.8)
+  Enabled: true
+Style/HashExcept: # (new in 1.7)
+  Enabled: true
+Style/IfWithBooleanLiteralBranches: # (new in 1.9)
+  Enabled: true
+Style/NegatedIfElseCondition: # (new in 1.2)
+  Enabled: true
+Style/NilLambda: # (new in 1.3)
+  Enabled: true
+Style/RedundantArgument: # (new in 1.4)
+  Enabled: true
+Style/SwapValues: # (new in 1.1)
+  Enabled: true
+
+############################################################
+# Added in RuboCop 1.10
+
+Gemspec/DateAssignment: # (new in 1.10)
+  Enabled: true
+Style/HashConversion: # (new in 1.10)
+  Enabled: true

data/.ruby-version

@@ -0,0 +1 @@
+2.7.5

data/.simplecov

@@ -0,0 +1,8 @@
+require 'simplecov-rcov'
+
+SimpleCov.start 'rails' do
+  add_filter 'module_info.rb'
+  coverage_dir 'artifacts'
+  formatter SimpleCov::Formatter::RcovFormatter
+  minimum_coverage 100
+end

data/.yardopts

@@ -0,0 +1,2 @@
+-m markdown
+-o ./artifacts/doc

data/CHANGES.md

@@ -0,0 +1,3 @@
+# 0.0.1 (25 January 2022)
+
+- initial public release

data/Dockerfile

@@ -0,0 +1,54 @@
+# =============================================================================
+# Target: base
+
+FROM ruby:3.0.2-alpine AS base
+
+RUN apk --no-cache --update upgrade && \
+    apk --no-cache add \
+        bash \
+        ca-certificates \
+        git \
+        libc6-compat \
+        openssl \
+        tzdata \
+        xz-libs \
+    && rm -rf /var/cache/apk/*
+
+WORKDIR /opt/app
+
+# =============================================================================
+# Target: development
+#
+
+FROM base AS development
+
+# Install system packages needed to build gems with C extensions.
+RUN apk --update --no-cache add \
+        build-base \
+        coreutils \
+        git \
+    && rm -rf /var/cache/apk/*
+
+# Copy codebase to WORKDIR. Unlike application projects, for a gem project
+# we need to do this before running `bundle install`, in order for the gem
+# we're building to be able to "install" itself.
+COPY . .
+
+# Install gems.
+RUN bundle install --path=/usr/local/bundle
+
+# =============================================================================
+# Target: production
+
+FROM base AS production
+
+# Copy the built codebase from the dev stage
+COPY --from=development /opt/app /opt/app
+COPY --from=development /usr/local/bundle /usr/local/bundle
+
+# Sanity-check that everything was installed correctly and still runs in the
+# slimmed-down production image.
+RUN bundle config set deployment 'true'
+RUN bundle install --local --path=/usr/local/bundle
+
+CMD ['bundle', 'exec', 'rake']

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Jenkinsfile

@@ -0,0 +1,18 @@
+#!/usr/bin/env groovy
+
+dockerComposePipeline(
+    commands: [
+        'bundle exec rake coverage',
+        'bundle exec rake rubocop',
+        'bundle exec rake bundle:audit',
+        'bundle exec rake gem'
+    ],
+    artifacts: [
+        junit: 'artifacts/rspec/**/*.xml',
+        html : [
+            'Code Coverage': 'artifacts/rcov',
+            'RuboCop'      : 'artifacts/rubocop'
+        ],
+        raw  : ['artifacts/**/*.gem']
+    ]
+)

data/LICENSE.md

@@ -0,0 +1,21 @@
+# The MIT License (MIT)
+
+Copyright © 2022 The Regents of the University of California
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the “Software”),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,210 @@
+# BerkeleyLibrary::Alma
+
+A utility gem for working with Alma / Primo.
+
+## Configuration
+
+The `BerkeleyLibrary::Alma::Config` class includes the options below. These
+can be read automatically from a Rails configuration
+(`Rails.application.config.alma_sru_host = "..."`, etc.) or set directly
+(`BerkeleyLibrary::Alma::Config.alma_sru_host = "..."`).
+
+Alternatively, `BerkeleyLibrary::Alma::Config.default!` will set the
+options to either:
+
+1. the value of the corresponding environment variable, if set, or
+2. the default value for the UC Berkeley Library.
+
+| Option                  | Environment variable        | Purpose                                                                                                                       | Berkeley default                  |
+| ---                     | ---                         | ---                                                                                                                           | ---                               |
+| `alma_sru_host`         | `LIT_ALMA_SRU_HOST`         | the Alma SRU hostname                                                                                                         | `berkeley.alma.exlibrisgroup.com` |
+| `alma_institution_code` | `LIT_ALMA_INSTITUTION_CODE` | the Alma institution code                                                                                                     | `search.library.berkeley.edu`     |
+| `alma_primo_host`       | `LIT_ALMA_PRIMO_HOST`       | the Alma Primo host                                                                                                           | `01UCS_BER`                       |
+| `alma_permalink_key`    | `LIT_ALMA_PERMALINK_KEY`    | the Alma [permalink key](https://knowledge.exlibrisgroup.com/Primo/Knowledge_Articles/What_is_the_key_in_short_permalinks%3F) | `iqob43`                          |
+
+## Retrieving Alma records
+
+The [`RecordId`](lib/berkeley_library/alma/record_id.rb) class encapsulates 
+an ID that can be used to look up records in Alma via 
+[SRU](https://developers.exlibrisgroup.com/alma/integrations/sru/).
+This can be either an Alma MMS ID:
+
+```ruby
+mms_id_str = '991054360089706532'
+record_id = BerkeleyLibrary::Alma::RecordId.parse(mms_id_str)
+# => #<BerkeleyLibrary::Alma::MMSID:0x0000000138949830 @institution="6532", @mms_id="991054360089706532", @type_prefix="99", @unique_part="105436008970">
+```
+
+Or a Millennium bib number:
+
+```ruby
+bib_number_str = 'b11082434'
+record_id = BerkeleyLibrary::Alma::RecordId.parse(bib_number_str)
+# => #<BerkeleyLibrary::Alma::BibNumber:0x0000000118815038 @check_str="9", @digit_str="11082434">
+```
+
+Given a `RecordId` object, you can get the SRU query URI for the corresponding MARC record:
+
+```ruby
+record_id.marc_uri
+# => #<URI::HTTPS https://berkeley.alma.exlibrisgroup.com/view/sru/01UCS_BER?version=1.2&operation=searchRetrieve&query=alma.mms_id%3D991054360089706532> 
+```
+
+Or the MARC XML as a string:
+
+```ruby
+marc_xml_str = record_id.get_marc_xml 
+# => "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?><searchRetrieveResponse>...</searchRetrieveResponse>"
+```
+
+Or just a [ruby-marc](https://github.com/ruby-marc/ruby-marc) `MARC::Record` object:
+
+```ruby
+marc_record = record_id.get_marc_record
+# => #<MARC::Record:0x0000000138b45490
+```
+
+#### Calculating the check digit for a Millennium bib
+
+You can also use `RecordId` to verify or calculate the check digit for a Millennium bib.
+
+(Check digit calculation is based on the algorithm described in 
+"[Recipe: Computing the Millennium checkdigit](http://liwong.blogspot.com/2018/04/recipe-computing-millennium-checkdigit.html)"
+by Lisa Wong of the McHenry Library, UC Santa Cruz.
+
+##### Calculating the check digit
+
+The check digit will be appended to bib numbers without one,
+or with the wildcard check digit `a`.
+
+```ruby
+bib_number_str = 'b11082434'
+record_id = BerkeleyLibrary::Alma::RecordId.parse(bib_number_str)
+# => #<BerkeleyLibrary::Alma::BibNumber:0x0000000118815038 @check_str="9", @digit_str="11082434">
+record_id.check_str
+# => "9"
+record_id.full_bib
+# => "b110824349" 
+
+bib_number_str = 'b11082434a'
+record_id = BerkeleyLibrary::Alma::RecordId.parse(bib_number_str)
+# => #<BerkeleyLibrary::Alma::BibNumber:0x0000000118815038 @check_str="9", @digit_str="11082434">
+```
+
+##### Verifying the check digit
+
+The `RecordId#parse` method will raise an error if passed a bib with a bad
+check digit.
+
+```ruby
+bib_number_str = 'b110824341' # wrong check digit; should be 9, not 2
+# bib_number.rb:78:in `ensure_check_digit': 110824341 check digit invalid: expected 9, got 1 (ArgumentError)
+# 	from /Users/david/Work/BerkeleyLibrary/alma/lib/berkeley_library/alma/bib_number.rb:68:in `split_bib'
+# 	from /Users/david/Work/BerkeleyLibrary/alma/lib/berkeley_library/alma/bib_number.rb:27:in `initialize'
+# 	from /Users/david/Work/BerkeleyLibrary/alma/lib/berkeley_library/alma/record_id.rb:35:in `new'
+# 	from /Users/david/Work/BerkeleyLibrary/alma/lib/berkeley_library/alma/record_id.rb:35:in `parse'
+```
+
+## Scripts
+
+### `alma-mms-lookup`: Control field 001 record ID lookup
+
+The `alma-mms-lookup` script takes one or more record IDs (either Millennium bib
+numbers or Alma MMS IDs) and attempts to read the corresponding MARC records via
+[SRU](https://developers.exlibrisgroup.com/alma/integrations/sru/) and extract
+the canonical MMS ID for the record from the 001 control field.
+
+#### Local execution
+
+If you clone this repository and run `bundle install` from the project root,
+you can run the `bin/alma-mms-lookup` script directly. Note that this requires
+Ruby 3.x to be installed. (Alternatively, you can use Docker; see below.)
+
+To look up a single ID:
+
+```sh
+echo b11082434 | bin/alma-mms-lookup
+```
+
+To look up a list of IDs given in a file `record-ids.txt`:
+
+```sh
+bin/alma-mms-lookup < record-ids.txt
+```
+
+#### Execution via Docker
+
+To look up a single ID:
+
+```sh
+echo b11082434 | docker compose run gem bin/alma-mms-lookup 
+```
+
+To look up a list of IDs given in a file `record-ids.txt`:
+
+```sh
+docker compose run gem bin/alma-mms-lookup < record-ids.txt
+```
+
+#### Output format
+
+The output is tab-separated, in the form
+
+```none
+<original bib number>	<bib number with check digit>	<MMS ID from 001>
+```
+
+or
+
+```none
+<orignal MMS id>	<original MMS ID again>	<MMS ID from 001>
+```
+
+e.g.:
+
+```none
+b11082434	b110824349	991038544199706532
+991038544199706532	991038544199706532	991038544199706532
+```
+
+Any IDs that cannot be retrieved or parsed are left blank:
+
+```sh
+echo 'b11082434
+b1234
+991038544199706532
+9912348245906531
+b110824349' | bin/alma-mms-lookup
+```
+
+produces:
+
+```none
+b11082434	b110824349	991038544199706532
+b1234		
+991038544199706532	991038544199706532	991038544199706532
+[2022-01-03T14:17:09.060-08:00] WARN: GET https://berkeley.alma.exlibrisgroup.com/view/sru/01UCS_BER?version=1.2&operation=searchRetrieve&query=alma.mms_id%3D9912348245906531 did not return a MARC record
+9912348245906531	9912348245906531
+b110824349	b110824349	991038544199706532
+```
+
+Note that warning messages are written to STDOUT, so you may need to filter them
+with `grep`:
+
+```sh
+echo 'b11082434
+b1234
+991038544199706532
+9912348245906531
+b110824349' | bin/alma-mms-lookup | grep -v WARN
+```
+
+produces:
+
+```none
+b11082434	b110824349	991038544199706532
+b1234		
+991038544199706532	991038544199706532	991038544199706532
+9912348245906531	9912348245906531	
+b110824349	b110824349	991038544199706532
+```

data/Rakefile

@@ -0,0 +1,20 @@
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('Gemfile', __dir__)
+require 'bundler/setup' # Set up gems listed in the Gemfile.
+
+# ------------------------------------------------------------
+# Application code
+
+File.expand_path('lib', __dir__).tap do |lib|
+  $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+end
+
+# ------------------------------------------------------------
+# CI
+
+ENV['RAILS_ENV'] = 'test' if ENV['CI']
+
+# ------------------------------------------------------------
+# Custom tasks
+
+desc 'Run tests, check test coverage, check code style, check for vulnerabilities, build gem'
+task default: %i[coverage rubocop bundle:audit gem]