neu-mods 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c0467914a611aa9d46065edcd2c0a18cd0decd642e769b70ecfaecc18e7ef1e
-  data.tar.gz: f97ba11b67874fefcb98f9de2af47eda370bb61f679e9b10994cf465b31876f2
+  metadata.gz: aa2cba0771dfcd203ae956c9f5a84cb58c004df684620e378bf4034b978ee6b3
+  data.tar.gz: e3610d3984fecaebccdb88032ab07b4fab55b0e6932ee5f54218b654016ceca5
 SHA512:
-  metadata.gz: 94029ec3b5d70d835677c4ad49cfc02bf7a501c782a91adb38c3a5cf6310ee727ffcef7736975526b699c796ff574ab3be5645ecaa7d576494b9b28c88c67ac1
-  data.tar.gz: 3b5c3b2f36af51e6af7424ff5ecdbf365a6c56358bf3aec3cff370b2473ad334cfaed9c20eae4aa2025ab583eb9d0ec9d7439d94fb7d8687e80dd301a64c7c38
+  metadata.gz: 8bcbcf544da159f6e2377ae868808e73e78d254e9c597e2dcd676d140cbb6f59a8624ca698233bd0ab18866c9438ddae988a7fc0ac485ce7fa3557c34d199a76
+  data.tar.gz: de478ac9c203c1edf05fb604c9da85b05e95e133fb20231716a6ef7dd9310292dacf753f13781d253ecbd93a04aa290e2eff40dc32c5331de0e278c1b07c736f

data/.version

@@ -1 +1 @@
-0.8.0
+0.10.0

data/README.md

@@ -50,6 +50,13 @@ doc.related_items  # => [{ type: "otherFormat", title: "..." }, ...]
                    #    every relatedItem that is not a series or a host
 doc.location       # => [{ physical_location:, shelf_location:, url: }, ...]
 doc.map_data       # => [{ scale:, projection:, coordinates: }, ...]
+doc.title_subjects # => ["The Great Gatsby"]   composed like the main title
+doc.hierarchical_geographic_subjects
+                   # => [{ country:, state:, city:, ... }, ...]   eleven levels,
+                   #    structured for the reason map_data is
+doc.record_info    # => { content_source:, origin:, description_standard:,
+                   #      creation_date:, change_date:, language_of_cataloging: }
+                   #    describes the CATALOGUING, not the resource
 doc.to_h           # => full projection, keyed to Atlas's Metadata::MODS attributes
 
 # The field registry -- the single declaration of what this gem projects.
@@ -73,7 +80,7 @@ doc.to_xml
 # node selection (for replace-on-save), and structure-aware build.
 doc.editable_personal_creators   # => [{ given:, family: }]  (plain, Creator role)
 doc.editable_corporate_creators  # => [{ name: }]
-doc.preserved_names              # => [{ name:, role: }]  (authority-bearing / non-Creator — read-only)
+doc.preserved_names              # => [{ name:, roles: }]  (authority-bearing / non-Creator — read-only)
 doc.editable_creator_nodes("personal")            # => live <name> nodes to replace
 doc.build_personal_name(given: "Jenny", family: "Smith")      # => a plain personal <name> node
 doc.build_corporate_name(name: "Northeastern University")     # => a plain corporate <name> node

data/lib/neu/mods/projection.rb

@@ -114,6 +114,26 @@ module NEU
         keyword_subjects.flat_map { |s| s.xpath("mods:topic", NAMESPACE).map { |t| t.text.strip } }
       end
 
+      # Neither child carries heading text: cartographics is a structured
+      # coordinate a reader reaches through #map_data, and geographicCode is a
+      # MARC code rather than a place name.
+      HEADING_OMITTED_CHILDREN = %w[cartographics geographicCode].freeze
+
+      # Every top-level <subject> as ONE heading, its parts in document order.
+      # A pre-coordinated heading like "Salt marshes--Massachusetts--20th
+      # century" is a single statement, and the per-axis fields below cannot say
+      # which parts belonged together: they pool every topic on the record into
+      # one list, so a fragment of a heading and a whole heading read alike.
+      #
+      # Kept in parts rather than joined. The separator is display policy, the
+      # same call #map_data makes for cartographics.
+      def subject_headings
+        doc.xpath("/mods:mods/mods:subject", NAMESPACE).filter_map do |node|
+          parts = subject_heading_parts(node)
+          { parts: parts } unless parts.empty?
+        end
+      end
+
       # Every <topic> under any top-level <subject> (the access-copy projection,
       # equivalent to Atlas's extract_topical_subjects).
       def topical_subjects = texts_at("/mods:mods/mods:subject/mods:topic")
@@ -130,6 +150,39 @@ module NEU
       def personal_name_subjects = name_subjects("personal")
       def corporate_name_subjects = name_subjects("corporate")
 
+      # The last unprojected member of a closed set: every other subject child
+      # already has a field, so leaving this one out made "what a subject can
+      # carry" arbitrary rather than complete.
+      def occupation_subjects = texts_at("/mods:mods/mods:subject/mods:occupation")
+
+      def genre_subjects = texts_at("/mods:mods/mods:subject/mods:genre")
+
+      # A MARC GAC code. Projected as the record wrote it: turning it into a
+      # place name needs a lookup table, which is the same call the gem already
+      # made for MARC relators -- the label vocabulary belongs to the consumer.
+      def geographic_code_subjects = texts_at("/mods:mods/mods:subject/mods:geographicCode")
+
+      # A subject that is a work has a nonSort, a subTitle and part numbers like
+      # any other titleInfo, so it composes through the same port as the main
+      # title rather than taking titleInfo/title alone.
+      def title_subjects
+        doc.xpath("/mods:mods/mods:subject/mods:titleInfo", NAMESPACE).filter_map { |node| composed_title_of(node) }
+      end
+
+      # Kept structured for the reason #map_data is. Flattening country / state
+      # / city into "United States -- New York (State) -- Parksville" would make
+      # a consumer that wants the city alone unpick a sentence.
+      #
+      # This is the axis bdr_43888.mods.xml uses INSTEAD of subject/geographic,
+      # so that record projected no place at all -- a live ingest path, not a
+      # hypothetical.
+      def hierarchical_geographic_subjects
+        doc.xpath("/mods:mods/mods:subject/mods:hierarchicalGeographic", NAMESPACE).filter_map do |node|
+          entry = HIERARCHICAL_GEOGRAPHIC_LEVELS.to_h { |level| [level, child_text(node, "mods:#{camelize(level)}")] }
+          entry if entry.values.any?
+        end
+      end
+
       # --- Names ---------------------------------------------------------------
 
       # One name as the access copy wants it. `affiliation` is how a reader
@@ -141,15 +194,17 @@ module NEU
       def name_entry(node)
         {
           name: name_display_value_w_date(node),
-          role: name_role(node),
+          roles: name_roles(node),
           affiliation: texts_under(node, "mods:affiliation")
         }
       end
 
-      # All top-level names as { name:, role: }. `name` reproduces the `mods` gem's
+      # All top-level names as { name:, roles: }. `name` reproduces the `mods` gem's
       # display_value_w_date (including its quirks -- faithfully, so existing Solr/
-      # display output is preserved). `role` prefers the type="text" roleTerm,
-      # falling back to the raw code (NOT MARC-relator-translated -- see README).
+      # display output is preserved). MODS repeats `role` on one name, and a
+      # cataloguer who records that a person both wrote and edited a work means
+      # both. Each term prefers the type="text" roleTerm, falling back to the raw
+      # code (NOT MARC-relator-translated -- see README).
       def names
         doc.xpath("/mods:mods/mods:name", NAMESPACE).map { |node| name_entry(node) }
       end
@@ -169,7 +224,7 @@ module NEU
 
       # Names the editable form does NOT manage (authority-bearing or non-Creator)
       # -- for read-only display ("these exist; edit via the XML tab"). Composed
-      # display string + role, like #names but filtered to the preserved set.
+      # display string + roles, like #names but filtered to the preserved set.
       def preserved_names
         doc.xpath("/mods:mods/mods:name", NAMESPACE)
            .reject { |node| editable_creator_name?(node) }
@@ -208,6 +263,30 @@ module NEU
       # back by nothing.
       def publication_information = texts_at("/mods:mods/mods:originInfo/mods:publisher")
       def edition = texts_at("/mods:mods/mods:originInfo/mods:edition")
+      def place_of_publication = texts_at("/mods:mods/mods:originInfo/mods:place/mods:placeTerm")
+      def issuance = texts_at("/mods:mods/mods:originInfo/mods:issuance")
+
+      # Serials. The @authority a record puts on a frequency is not projected:
+      # authority handling is a question the gem defers everywhere else -- for
+      # genre, subject and name -- and answering it for one field would be
+      # inconsistent.
+      def frequency = texts_at("/mods:mods/mods:originInfo/mods:frequency")
+
+      def table_of_contents = texts_at("/mods:mods/mods:tableOfContents")
+      def reformatting_quality = texts_at("/mods:mods/mods:physicalDescription/mods:reformattingQuality")
+
+      # A note about the object rather than about the work -- "Scanned at 600
+      # dpi" belongs beside the extent, not beside a content note. Projected as
+      # plain strings like its physicalDescription siblings: #notes keeps @type
+      # because the type changes what a top-level note means, and nothing here
+      # turns on it.
+      def physical_description_notes = texts_at("/mods:mods/mods:physicalDescription/mods:note")
+
+      # An LCC or DDC call number. Note this is NOT the same concept as Atlas's
+      # classification_ssim, which carries a FileSet content-type vocabulary --
+      # the name collision is accidental and the consumer has to pick a free
+      # Solr field.
+      def classification = texts_at("/mods:mods/mods:classification")
 
       # Every top-level note, keeping its @type. The type carries meaning -- a
       # "statement of responsibility" is not a "funding" note -- so flattening
@@ -253,7 +332,18 @@ module NEU
       end
 
       def related_series = related_item_titles("series")
-      def host_collections = related_item_titles("host")
+
+      # The host's title plus THIS work's position within it. The host's own
+      # name, originInfo and identifier stay out: they belong to the other
+      # record, and a transcribed copy goes stale the moment that record is
+      # edited. A part is the exception, because a volume, issue and page range
+      # describe this article and no other record holds that fact.
+      def host_collections
+        doc.xpath("/mods:mods/mods:relatedItem[@type='host']", NAMESPACE).filter_map do |node|
+          title = child_text(node, "mods:titleInfo/mods:title")
+          { title: title, **host_part(node) } if title
+        end
+      end
 
       # relatedItem @type values that already have a field of their own, so the
       # catch-all below does not repeat them.
@@ -297,6 +387,26 @@ module NEU
       # or a full date. Matching the shape explicitly, rather than widening
       # DateTime.parse, is what lets the declared precision fall out of the parse
       # instead of being guessed after it.
+      # The eleven children the XSD allows under hierarchicalGeographic, in the
+      # order MODS lists them -- broadest first, which is also the order a
+      # consumer composing a place string wants to reverse.
+      HIERARCHICAL_GEOGRAPHIC_LEVELS = %i[
+        continent country province region state territory county city
+        city_section island area
+      ].freeze
+
+      # recordInfo children. Read as a single value: the schema repeats the
+      # element, but a record with two cataloguing provenances is not a case
+      # anyone has, and an array here buys nothing.
+      RECORD_INFO_PARTS = {
+        content_source: "mods:recordContentSource",
+        origin: "mods:recordOrigin",
+        description_standard: "mods:descriptionStandard",
+        creation_date: "mods:recordCreationDate",
+        change_date: "mods:recordChangeDate",
+        language_of_cataloging: "mods:languageOfCataloging/mods:languageTerm"
+      }.freeze
+
       W3CDTF_DATE = /\A(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?\z/
 
       # What #date_parts returns when the element is absent entirely, so an
@@ -351,6 +461,19 @@ module NEU
       def date_issued_with_precision = [date_issued, date_issued_precision]
       def copyright_date_with_precision = [copyright_date, copyright_date_precision]
 
+      # Who catalogued this record, to what standard, and when. It describes the
+      # CATALOGUING rather than the resource, which is why it is one value and
+      # why a consumer is unlikely to want it beside Publisher -- but dropping a
+      # preservation repository's provenance statement on read is wrong on its
+      # face, so it is projected and the display question is the consumer's.
+      def record_info
+        node = doc.at_xpath("/mods:mods/mods:recordInfo", NAMESPACE)
+        return nil unless node
+
+        entry = RECORD_INFO_PARTS.transform_values { |xpath| child_text(node, xpath) }
+        entry if entry.values.any?
+      end
+
       # --- Full projection -----------------------------------------------------
 
       # The field registry: the single declaration of what this gem projects.
@@ -379,7 +502,10 @@ module NEU
 
         # origin
         publication_information: :many,
+        place_of_publication: :many,
         edition: :many,
+        issuance: :many,
+        frequency: :many,
         # Six rows per originInfo date. Flat rather than one nested value,
         # because the value half has consumers that need a real date object.
         date_created: :one,
@@ -407,14 +533,23 @@ module NEU
         format: :many,
         extent: :many,
         digital_origin: :many,
+        reformatting_quality: :many,
+        physical_description_notes: :many,
         notes: :many,
+        table_of_contents: :many,
 
         # subjects
+        subject_headings: :many,
         topical_subjects: :many,
         geographic_subjects: :many,
         temporal_subjects: :many,
         personal_name_subjects: :many,
         corporate_name_subjects: :many,
+        occupation_subjects: :many,
+        genre_subjects: :many,
+        geographic_code_subjects: :many,
+        title_subjects: :many,
+        hierarchical_geographic_subjects: :many,
         map_data: :many,
 
         # related items
@@ -424,7 +559,9 @@ module NEU
 
         # identifiers and location
         identifiers: :many,
+        classification: :many,
         permanent_url: :one,
+        record_info: :one,
         location: :many,
 
         # access
@@ -547,6 +684,13 @@ module NEU
       # A variant title composed the way the access copy wants it: normalised
       # first, like #access_title_parts, so a curly quote or an invisible format
       # mark cannot reach Solr or a display template through this route either.
+      # One titleInfo composed the way the access copy wants it, shared by the
+      # subject-title axis and the assembled heading so the two cannot drift.
+      def composed_title_of(node)
+        parts = title_parts_of(node).transform_values { |value| NEU::MODS.normalize(value.to_s) }
+        clean(Projection.compose_title(parts))
+      end
+
       def variant_titles(type)
         doc.xpath("/mods:mods/mods:titleInfo[@type='#{type}']", NAMESPACE).filter_map do |node|
           parts = title_parts_of(node).transform_values { |value| NEU::MODS.normalize(value.to_s) }
@@ -559,10 +703,54 @@ module NEU
            .filter_map { |node| name_display_value_w_date(node) }
       end
 
+      def subject_heading_parts(node)
+        node.xpath("mods:*", NAMESPACE).flat_map { |child| subject_heading_part(child) }.compact
+      end
+
+      def subject_heading_part(child)
+        return [] if HEADING_OMITTED_CHILDREN.include?(child.name)
+
+        case child.name
+        when "name" then [name_display_value_w_date(child)]
+        when "titleInfo" then [composed_title_of(child)]
+        # Each level is its own part, so a hierarchical place reads as the steps
+        # of the heading rather than as one run-together string.
+        when "hierarchicalGeographic" then child.xpath("mods:*", NAMESPACE).map { |level| clean(level.text) }
+        else split_heading_text(clean(child.text))
+        end
+      end
+
+      # A cataloguer who typed a whole heading into one element as "A--B--C"
+      # made the same statement as one who structured it into siblings, so both
+      # arrive here as the same parts.
+      def split_heading_text(text)
+        return [] if text.nil?
+        return [text] unless text.include?("--")
+
+        text.split("--").filter_map { |part| clean(part) }
+      end
+
       def related_item_titles(type)
         texts_at("/mods:mods/mods:relatedItem[@type='#{type}']/mods:titleInfo/mods:title")
       end
 
+      # Kept in parts rather than composed into "24(3), pp. 210-218". The
+      # punctuation of a citation is display policy, the same call #map_data
+      # makes for cartographics. MODS leaves @unit optional, so a page extent
+      # without one is read rather than dropped.
+      def host_part(node)
+        part = node.at_xpath("mods:part", NAMESPACE)
+        return {} if part.nil?
+
+        pages = "mods:extent[@unit='page' or not(@unit)]"
+        {
+          volume: child_text(part, "mods:detail[@type='volume']/mods:number"),
+          issue: child_text(part, "mods:detail[@type='issue']/mods:number"),
+          start_page: child_text(part, "#{pages}/mods:start"),
+          end_page: child_text(part, "#{pages}/mods:end")
+        }.compact
+      end
+
       def text_at(xpath)
         node = doc.at_xpath(xpath, NAMESPACE)
         node ? NEU::MODS.canonical_ws(node.text) : ""
@@ -575,6 +763,13 @@ module NEU
       # [nil], and every consumer of that array has to guard for it.
       # #texts_at scoped to a node rather than the document, for a repeatable
       # child of one element.
+      # :city_section -> "citySection". The level names are snake_case in the
+      # projection and camelCase in the schema.
+      def camelize(level)
+        head, *rest = level.to_s.split("_")
+        [head, *rest.map(&:capitalize)].join
+      end
+
       def texts_under(node, xpath)
         node.xpath(xpath, NAMESPACE).filter_map { |child| clean(child.text) }
       end
@@ -682,14 +877,16 @@ module NEU
             .map(&:text).join(" ")
       end
 
-      def name_role(node)
-        node.xpath("mods:role", NAMESPACE).each do |role|
-          val = role_term_value(role)
-          return val if val
-        end
-        nil
+      def name_roles(node)
+        node.xpath("mods:role", NAMESPACE).filter_map { |role| role_term_value(role) }
       end
 
+      # The first declared role, which is what decides whether the simple edit
+      # form owns a name. Deliberately not #name_roles.include?("Creator"):
+      # widening it would hand the form a name whose other roles it cannot
+      # represent, and saving would drop them from the preservation XML.
+      def name_role(node) = name_roles(node).first
+
       # Prefer the type="text" roleTerm; fall back to the raw type="code" term
       # (NOT MARC-relator-translated -- see README). nil if neither is present.
       def role_term_value(role)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: neu-mods
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri