neu-mods 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5416d755319f464e252ef4fa07d0372efb11e1379d76ad6155b78f42a61c221a
-  data.tar.gz: ddfcf9eb792155c216bf9710ef6cfcc379f914791a782da30577158bb02a1da7
+  metadata.gz: aa2cba0771dfcd203ae956c9f5a84cb58c004df684620e378bf4034b978ee6b3
+  data.tar.gz: e3610d3984fecaebccdb88032ab07b4fab55b0e6932ee5f54218b654016ceca5
 SHA512:
-  metadata.gz: d465b12175d8b15f7da7d7c355af0246294b3e7df0c276be775b6ccf41c14840f716fa7624ed86a54bff69da56625041cf7ca1f245e9ff6bb8f4035b44f70799
-  data.tar.gz: ce373c9bb16d1a7e6142a4e0556e669ddb07d0bbe77db172f7954d4d54eb298b4a688c5cf3a60bd5237611670bbfb162c67d7d9c1bd5377a6579d0c78b9a9030
+  metadata.gz: 8bcbcf544da159f6e2377ae868808e73e78d254e9c597e2dcd676d140cbb6f59a8624ca698233bd0ab18866c9438ddae988a7fc0ac485ce7fa3557c34d199a76
+  data.tar.gz: de478ac9c203c1edf05fb604c9da85b05e95e133fb20231716a6ef7dd9310292dacf753f13781d253ecbd93a04aa290e2eff40dc32c5331de0e278c1b07c736f

data/.version

@@ -1 +1 @@
-0.9.0
+0.10.0

data/README.md

@@ -80,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,11 @@ 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
@@ -141,10 +166,7 @@ module NEU
       # 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 do |node|
-          parts = title_parts_of(node).transform_values { |value| NEU::MODS.normalize(value.to_s) }
-          clean(Projection.compose_title(parts))
-        end
+        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
@@ -172,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
@@ -200,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) }
@@ -251,6 +275,13 @@ module NEU
       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
@@ -301,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.
@@ -492,15 +534,18 @@ module NEU
         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,
@@ -639,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) }
@@ -651,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) : ""
@@ -781,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.9.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