neu-mods 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ab1cb07bf4122e98017ded99c790824865f68fb8ccdfdcbb3b5fc8e7d72cbf55
+  data.tar.gz: 6d3b467da6fde096e0ea26f9e76c447ea24c563c6cc5fd1a47e06b8f18d72aca
+SHA512:
+  metadata.gz: 4c9b5a6006cf0ab3faced2d60f49f703ab482f28f2208d39c5225bd7af769c4f6bba634b0808d83d3b5ac3f2210efca07f8b1ad37976e0ed17d1175d666fcccf
+  data.tar.gz: 2c92060d9faddce439bb9b462982fbb186f6d792f5fc86cfa9702a7cf1c2118c06a3236a5e0875c2499e5593083f531a5668c841696168d330c6527728ca56a7

data/.version

@@ -0,0 +1 @@
+0.1.0

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in neu-mods.gemspec
+gemspec
+
+gem "rake", "~> 13.0"

data/README.md

@@ -0,0 +1,83 @@
+# neu-mods
+
+Northeastern-flavored MODS v3 **projection + selection** for the DRS, shared by
+[Cerberus](https://github.com/NEU-Libraries/cerberus) (front end) and
+[Atlas](https://github.com/NEU-Libraries/atlas) (API backend).
+
+It is a **Nokogiri-native, dependency-light contract over MODS documents** — pure
+functions over a parsed document, nothing else. No Rails, no persistence, no
+HTTP. It answers two questions:
+
+- **"Where is X?"** — `Selectors` return *live Nokogiri nodes*, so they serve both
+  the read path (projection reads their text) and the write path (an editor
+  mutates the returned node in place). The node an editor changes is provably the
+  node the projection reads.
+- **"What does this project to?"** — `Projection` returns *plain data*
+  (hashes/strings/arrays — never opaque typed objects) for indexing/display.
+
+It depends on **Nokogiri alone** — deliberately *not* the `sul-dlss/mods` +
+`nom-xml` stack (which is sunsetting alongside Stanford's move to Cocina). See
+the design note in the DRS gap-reports for the full rationale.
+
+## Usage
+
+```ruby
+require "neu-mods"
+
+doc = NEU::MODS::Document.parse(xml_string)
+
+# Projection (plain data)
+doc.plain_title    # => "What's New - How We Respond to Disaster, Episode 1"
+doc.title_parts    # => { non_sort:, subtitle:, title:, part_name:, part_number: }
+doc.abstract       # => normalized, paragraph-joined String
+doc.topical_subjects # => ["Civil society", ...]   (every <topic>, for the access copy)
+doc.keywords       # => [...]   (only the editable attribute-free keyword subjects)
+doc.to_h           # => full projection, keyed to Atlas's Metadata::MODS attributes
+
+# Selectors (live nodes — for editing)
+node = doc.primary_title_info.at_xpath("mods:title", NEU::MODS::NAMESPACE)
+node.content = "New Title" unless NEU::MODS.whitespace_equivalent?(node.text, "New Title")
+doc.to_xml
+```
+
+## Two normalizers, two jobs
+
+- `NEU::MODS.whitespace_equivalent?` / `.canonical_ws` — the **no-op guard**: did an
+  edit change anything, or only insignificant whitespace? (Used to avoid minting
+  an unchanged OCFL MODS version.)
+- `NEU::MODS.normalize_paragraphs` / `.normalize` — clean **curator freetext** for
+  the JSON/Solr access copy (dash/smart-punctuation transliteration, control
+  stripping, paragraph handling). The XML preservation copy is never touched.
+
+## Behavior fidelity & known caveats
+
+The projection is **behavior-preserving** with Atlas's prior `mods`-gem-based
+extraction, pinned by `spec/conformance_spec.rb` against `work-mods.xml`. Two
+intentional notes:
+
+- **Name display** reproduces the `mods` gem's `display_value_w_date` *including
+  its quirks* (e.g. multiple `given` nameParts concatenate with no separator),
+  to preserve existing Solr/display output. Cleanups are a deliberate future
+  contract change, not a silent one.
+- **Roles & languages** read the `type="text"` term and fall back to the **raw
+  code** — they are *not* MARC-relator / ISO-639 translated. Records carrying
+  text forms (the norm) are unaffected; code-only records would differ. Vendoring
+  those lookup tables (or depending on `iso-639`) is deferred to keep the gem
+  Nokogiri-only and small.
+
+## Source convention
+
+Every character-class regex in `TextNormalizer` is built **programmatically from
+codepoints**, so the source stays pure ASCII (no literal smart-quotes/dashes, no
+raw control bytes). A spec enforces this. Keep it that way.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+Versioned via the `.version` file (read by `lib/neu/mods/version.rb`); released
+with `bundler/gem_tasks` (`rake release`), mirroring `atlas_rb`.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/neu/mods/canonicalize.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module NEU
+  module MODS
+    # Lightweight whitespace canonicalization used by the *no-op guard* -- does an
+    # edit actually change anything, or only insignificant whitespace? (Cerberus's
+    # MODSMerge uses this to avoid minting an unchanged OCFL MODS version.) This is
+    # deliberately distinct from TextNormalizer below: this one only folds
+    # whitespace; TextNormalizer cleans curator freetext for the access copy.
+    module Canonicalize
+      module_function
+
+      NBSP = [0xA0].pack("U") # U+00A0 non-breaking space, built from codepoint
+
+      # \s doesn't match U+00A0 (NBSP) in Ruby's default mode, so fold NBSP to a
+      # plain space first, then collapse any whitespace run to one space + strip.
+      def canonical_ws(str)
+        str.to_s.tr(NBSP, " ").gsub(/\s+/, " ").strip
+      end
+
+      # Treat values differing only by insignificant whitespace (NBSP vs space,
+      # collapsible runs, leading/trailing) as equal.
+      def whitespace_equivalent?(current, incoming)
+        canonical_ws(current) == canonical_ws(incoming)
+      end
+    end
+
+    # Normalises curator-authored freetext on the way into the JSON access copy
+    # (and Solr); the XML preservation copy stays untouched. Ported from Atlas's
+    # TextNormalizer (which carries DRS v1 prior art) so the gem reproduces Atlas's
+    # projection byte-for-byte.
+    #
+    # IMPORTANT: every character-class regex is built *programmatically* from
+    # codepoint lists via `format('\\u%04X', cp)`, so this source file stays pure
+    # ASCII -- no literal smart-quotes, dashes, or (critically) raw control bytes
+    # land on disk. Keep it that way.
+    #
+    # Pipeline: force UTF-8 + scrub invalid bytes; NFC; map Unicode dashes to '-'
+    # (swung-dash to '~'); transliterate the General Punctuation block (smart
+    # quotes, ellipsis, etc.) to ASCII; strip C0/C1 controls (keeping tab/newline);
+    # collapse horizontal-whitespace runs to one space; for paragraph fields,
+    # collapse 2+ newlines to exactly two; strip.
+    #
+    #   .normalize(str)            -- single-line fields (newlines -> spaces)
+    #   .normalize_paragraphs(str) -- fields that may carry paragraph breaks
+    #                                 (abstract, accessCondition)
+    module TextNormalizer
+      module_function
+
+      # Build a character-class Regexp from an array of integer codepoints, as
+      # \uXXXX escapes (keeps this source ASCII).
+      def self.char_class(codepoints, prefix: "")
+        Regexp.new("[#{prefix}#{codepoints.map { |cp| format('\\u%04X', cp) }.join}]")
+      end
+
+      # NOTE: U+2053 (swung dash) is intentionally excluded from dashes -- it is
+      # named "dash" but conventionally maps to ASCII '~', not '-' (V1 prior art).
+      DASH_CODEPOINTS = [
+        0x002D, 0x00AD, 0x058A, 0x05BE, 0x1400, 0x1806,
+        0x2010, 0x2011, 0x2012, 0x2013, 0x2014, 0x2015,
+        0x2043, 0x207B, 0x208B, 0x2212,
+        0x2E17, 0x2E1A, 0x2E3A, 0x2E3B, 0x2E40,
+        0x301C, 0x3030, 0x30A0, 0xFE31, 0xFE32, 0xFE58,
+        0xFE63, 0xFF0D
+      ].freeze
+      DASH_RE = char_class(DASH_CODEPOINTS).freeze
+
+      SWUNG_DASH_RE = Regexp.new(format('\\u%04X', 0x2053)).freeze
+
+      # C0 (U+0000..U+0008, U+000B..U+001F) and C1 (U+007F..U+009F). U+0009 (tab)
+      # and U+000A (newline) are preserved.
+      CONTROL_CODEPOINTS = ((0x0000..0x0008).to_a + (0x000B..0x001F).to_a + (0x007F..0x009F).to_a).freeze
+      CONTROL_RE = char_class(CONTROL_CODEPOINTS).freeze
+
+      HORIZONTAL_WS_CODEPOINTS = [
+        0x0009, 0x00A0, 0x1680,
+        0x2000, 0x2001, 0x2002, 0x2003, 0x2004, 0x2005, 0x2006,
+        0x2007, 0x2008, 0x2009, 0x200A, 0x202F, 0x205F, 0x3000
+      ].freeze
+      # Leading literal space included in the class (the " " prefix); `+` so a run
+      # of horizontal whitespace collapses to a single space.
+      HORIZONTAL_WS_RE = Regexp.new("#{char_class(HORIZONTAL_WS_CODEPOINTS, prefix: " ").source}+").freeze
+
+      PARAGRAPH_RUN_RE = /\n{2,}/
+
+      # General Punctuation block (U+2000..U+206F). Codepoints not listed pass
+      # through unchanged. Empty-string values deliberately drop invisible/bidi/
+      # format marks so they cannot leak into the access copy.
+      GENERAL_PUNCTUATION = {
+        0x2000 => " ", 0x2001 => " ", 0x2002 => " ", 0x2003 => " ",
+        0x2004 => " ", 0x2005 => " ", 0x2006 => " ", 0x2007 => " ",
+        0x2008 => " ", 0x2009 => " ", 0x200A => " ",
+        0x200B => "",  0x200C => "",  0x200D => "",
+        0x200E => "",  0x200F => "",
+        0x2018 => "'", 0x2019 => "'", 0x201A => ",", 0x201B => "'",
+        0x201C => '"', 0x201D => '"', 0x201E => '"', 0x201F => '"',
+        0x2020 => "+", 0x2021 => "+",
+        0x2022 => "*", 0x2023 => "*", 0x2024 => ".", 0x2025 => "..",
+        0x2026 => "...",
+        0x2028 => "\n", 0x2029 => "\n\n",
+        0x202A => "",  0x202B => "", 0x202C => "", 0x202D => "",
+        0x202E => "",  0x202F => " ",
+        0x2030 => "%", 0x2032 => "'", 0x2033 => '"', 0x2035 => "'",
+        0x2036 => '"',
+        0x2039 => "<", 0x203A => ">", 0x203C => "!!", 0x203D => "?",
+        0x2044 => "/", 0x2052 => "%",
+        0x205F => " ", 0x2060 => "", 0x2061 => "", 0x2062 => "",
+        0x2063 => "",  0x2064 => "",
+        0x206A => "",  0x206B => "", 0x206C => "", 0x206D => "",
+        0x206E => "",  0x206F => ""
+      }.transform_keys { |cp| [cp].pack("U") }.freeze
+      GENERAL_PUNCTUATION_RE = Regexp.new("[#{format('\\u%04X-\\u%04X', 0x2000, 0x206F)}]").freeze
+
+      def normalize(str)
+        return "" if str.nil?
+
+        s = base_normalize(str.to_s)
+        s = s.tr("\n", " ")
+        s.gsub(HORIZONTAL_WS_RE, " ").strip
+      end
+
+      def normalize_paragraphs(str)
+        return "" if str.nil?
+
+        s = base_normalize(str.to_s)
+        s = s.gsub(HORIZONTAL_WS_RE, " ")
+        s = s.gsub(/ *\n */, "\n")
+        s.split(PARAGRAPH_RUN_RE).map { |p| p.tr("\n", " ").strip }
+                                 .reject(&:empty?).join("\n\n")
+      end
+
+      def base_normalize(str)
+        s = str.dup.force_encoding("UTF-8")
+        s = s.scrub("")
+        s = s.unicode_normalize(:nfc)
+        s = s.gsub(DASH_RE, "-")
+        s = s.gsub(SWUNG_DASH_RE, "~")
+        s = s.gsub(GENERAL_PUNCTUATION_RE) { |c| GENERAL_PUNCTUATION.fetch(c, c) }
+        s.gsub(CONTROL_RE, "")
+      end
+    end
+  end
+end

data/lib/neu/mods/document.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module NEU
+  module MODS
+    # The gem's main entry point: a thin facade over a parsed MODS document.
+    #
+    #   doc = NEU::MODS::Document.parse(xml)
+    #   doc.plain_title            # => composed display title
+    #   doc.to_h                   # => full read projection
+    #   doc.primary_title_info     # => a live Nokogiri node (for editing)
+    #
+    # Selectors return live nodes (shared by read and write); projection methods
+    # return plain data. Parsing uses `&:noblanks` to match Atlas's read and to
+    # avoid spurious whitespace-only text nodes.
+    class Document
+      include Selectors
+      include Projection
+
+      attr_reader :doc
+
+      def self.parse(xml)
+        new(Nokogiri::XML(xml.to_s, &:noblanks))
+      end
+
+      # Wrap an already-parsed Nokogiri document (used by writers that own the doc
+      # they're mutating, so selectors and serialization share one instance).
+      def initialize(nokogiri_doc)
+        @doc = nokogiri_doc
+      end
+
+      def to_xml(...)
+        doc.to_xml(...)
+      end
+    end
+  end
+end

data/lib/neu/mods/projection.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require "date"
+
+module NEU
+  module MODS
+    # Node -> plain data. The read contract: what a MODS document *projects to* for
+    # indexing/display. Behavior-preserving with Atlas's prior `mods`-gem-based
+    # extraction (verified by the conformance corpus), reimplemented in Nokogiri so
+    # DRS depends on Nokogiri alone. Mixed into Document; operates on `doc`.
+    #
+    # Empty-value conventions mirror Atlas: scalar fields are "" when absent
+    # (matching `.text.squish` on an empty node set), except `permanent_url` and
+    # `date_created`, which are nil when their node is absent. Arrays are [].
+    module Projection
+      # --- Title ---------------------------------------------------------------
+
+      # Structured primary-title parts. nil for an absent part (the Cerberus form
+      # treats nil as "not present"); to_h coerces to "" for the Atlas main_title.
+      def title_parts
+        ti = primary_title_info
+        {
+          non_sort: child_text(ti, "mods:nonSort"),
+          subtitle: child_text(ti, "mods:subTitle"),
+          title: child_text(ti, "mods:title"),
+          part_name: child_text(ti, "mods:partName"),
+          part_number: child_text(ti, "mods:partNumber")
+        }
+      end
+
+      # Composed display title (the former Atlas MODSDecoration#plain_title), driven
+      # off the scoped primary title.
+      def plain_title
+        p = title_parts
+        return "" if blank?(p[:title])
+
+        "#{p[:non_sort]}#{p[:title]}" +
+          prefix(": ", p[:subtitle]) +
+          prefix(" - ", p[:part_name]) +
+          prefix(", ", p[:part_number])
+      end
+
+      # --- Abstract / access ---------------------------------------------------
+
+      def abstract
+        join_paragraphs(abstract_nodes)
+      end
+
+      def access_condition
+        join_paragraphs(doc.xpath("/mods:mods/mods:accessCondition", NAMESPACE))
+      end
+
+      # --- Subjects ------------------------------------------------------------
+
+      # The editable free-text keyword set (Cerberus simple form): topics under the
+      # attribute-free keyword subjects only.
+      def keywords
+        keyword_subjects.flat_map { |s| s.xpath("mods:topic", NAMESPACE).map { |t| t.text.strip } }
+      end
+
+      # Every <topic> under any top-level <subject> (the access-copy projection,
+      # equivalent to Atlas's extract_topical_subjects).
+      def topical_subjects
+        doc.xpath("/mods:mods/mods:subject/mods:topic", NAMESPACE).map { |t| clean(t.text) }
+      end
+
+      # --- Names ---------------------------------------------------------------
+
+      # All top-level names as { name:, role: }. `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).
+      def names
+        doc.xpath("/mods:mods/mods:name", NAMESPACE).map do |node|
+          { name: name_display_value_w_date(node), role: name_role(node) }
+        end
+      end
+
+      # --- Scalars / simple arrays --------------------------------------------
+
+      def languages
+        doc.xpath("/mods:mods/mods:language", NAMESPACE).map do |lang|
+          term = lang.at_xpath("mods:languageTerm[@type='text']", NAMESPACE) ||
+                 lang.at_xpath("mods:languageTerm", NAMESPACE)
+          clean(term&.text)
+        end.compact
+      end
+
+      def resource_type = text_at("/mods:mods/mods:typeOfResource")
+      def format = text_at("/mods:mods/mods:physicalDescription/mods:form")
+      def extent = text_at("/mods:mods/mods:physicalDescription/mods:extent")
+      def digital_origin = text_at("/mods:mods/mods:physicalDescription/mods:digitalOrigin")
+
+      def genres
+        doc.xpath("/mods:mods/mods:genre", NAMESPACE).map { |g| clean(g.text) }
+      end
+
+      def related_series
+        doc.xpath("/mods:mods/mods:relatedItem[@type='series']/mods:titleInfo/mods:title", NAMESPACE)
+           .map { |t| clean(t.text) }
+      end
+
+      def identifiers
+        doc.xpath("/mods:mods/mods:identifier", NAMESPACE).map { |i| clean(i.text) }
+      end
+
+      def permanent_url
+        node = doc.at_xpath("/mods:mods/mods:identifier[@type='hdl']", NAMESPACE)
+        node && clean(node.text)
+      end
+
+      # Parsed dateCreated, or nil if no originInfo/dateCreated, or "" if present
+      # but unparseable (mirrors Atlas's safe_date_parse rescue).
+      def date_created
+        node = doc.at_xpath("/mods:mods/mods:originInfo/mods:dateCreated", NAMESPACE)
+        return nil unless node
+
+        str = NEU::MODS.canonical_ws(node.text)
+        return nil if str.empty?
+
+        begin
+          DateTime.parse(str)
+        rescue Date::Error
+          ""
+        end
+      end
+
+      # --- Full projection -----------------------------------------------------
+
+      # The complete read projection, keyed to Atlas's Metadata::MODS attribute
+      # names -- a drop-in source for `convert_xml_to_json`.
+      def to_h
+        {
+          main_title: title_parts.transform_values(&:to_s),
+          names: names,
+          languages: languages,
+          date_created: date_created,
+          resource_type: resource_type,
+          genres: genres,
+          format: format,
+          extent: extent,
+          digital_origin: digital_origin,
+          abstract: abstract,
+          related_series: related_series,
+          topical_subjects: topical_subjects,
+          identifiers: identifiers,
+          permanent_url: permanent_url,
+          access_condition: access_condition
+        }
+      end
+
+      private
+
+      # --- helpers -------------------------------------------------------------
+
+      def text_at(xpath)
+        node = doc.at_xpath(xpath, NAMESPACE)
+        node ? NEU::MODS.canonical_ws(node.text) : ""
+      end
+
+      def child_text(parent, xpath)
+        return nil unless parent
+
+        node = parent.at_xpath(xpath, NAMESPACE)
+        return nil unless node
+
+        v = NEU::MODS.canonical_ws(node.text)
+        v.empty? ? nil : v
+      end
+
+      # canonical_ws, but nil for blank (used where an absent member must drop out).
+      def clean(str)
+        return nil if str.nil?
+
+        v = NEU::MODS.canonical_ws(str)
+        v.empty? ? nil : v
+      end
+
+      def blank?(str)
+        str.nil? || str.strip.empty?
+      end
+
+      def prefix(sep, val)
+        blank?(val) ? "" : "#{sep}#{val}"
+      end
+
+      def join_paragraphs(nodes)
+        nodes.map { |n| NEU::MODS.normalize_paragraphs(n.text) }.reject(&:empty?).join("\n\n")
+      end
+
+      # --- name display (faithful port of mods gem display_value_w_date) -------
+
+      def name_display_value_w_date(node)
+        dv = name_display_value(node)
+        node.xpath("mods:namePart[@type='date']", NAMESPACE).each do |np|
+          d = np.text
+          dv += ", #{d}" unless d.empty? || dv.end_with?(d)
+        end
+        dv = dv.sub(/\A, /, "")
+        dv.strip.empty? ? nil : dv.strip
+      end
+
+      def name_display_value(node)
+        display_form = node.at_xpath("mods:displayForm", NAMESPACE)
+        return display_form.text if display_form && !display_form.text.empty?
+
+        if node["type"] == "personal"
+          personal_display_value(node)
+        else
+          non_date_parts_joined(node)
+        end
+      end
+
+      def personal_display_value(node)
+        family = joined_parts(node, "family")
+        given  = joined_parts(node, "given")
+        dv =
+          if family.empty?
+            given
+          else
+            given.empty? ? family : "#{family}, #{given}"
+          end
+
+        return non_date_parts_joined(node) if dv.empty?
+
+        append_terms_of_address(node, dv)
+      end
+
+      def append_terms_of_address(node, dv)
+        first = true
+        node.xpath("mods:namePart[@type='termsOfAddress']", NAMESPACE).each do |np|
+          next if np.text.empty?
+
+          dv += first ? " #{np.text}" : ", #{np.text}"
+          first = false
+        end
+        dv
+      end
+
+      # NodeSet-style concatenation: the `mods` gem joins same-typed nameParts via
+      # NodeSet#text (no separator) -- e.g. two `given` parts become "A.(B)". We
+      # reproduce that (quirk included) to stay behavior-preserving.
+      def joined_parts(node, type)
+        node.xpath("mods:namePart[@type='#{type}']", NAMESPACE).map(&:text).join
+      end
+
+      def non_date_parts_joined(node)
+        node.xpath("mods:namePart", NAMESPACE)
+            .reject { |np| np["type"] == "date" || np.text.empty? }
+            .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
+      end
+
+      # 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)
+        %w[text code].each do |type|
+          term = role.at_xpath("mods:roleTerm[@type='#{type}']", NAMESPACE)
+          text = term&.text.to_s.strip
+          return text unless text.empty?
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/neu/mods/selectors.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module NEU
+  module MODS
+    # Node LOCATION over a parsed MODS document. These return live Nokogiri nodes,
+    # so they serve BOTH the read path (projection reads their text) AND the write
+    # path (Cerberus's MODSMerge mutates the returned nodes in place). That shared
+    # definition is the point: the node an editor changes is provably the node the
+    # projection reads. Mixed into Document; operates on `doc`.
+    module Selectors
+      # Top-level primary titleInfo, falling back to the first top-level titleInfo.
+      # Scoped to direct children of <mods:mods> so a relatedItem's nested
+      # titleInfo (e.g. a series title) is never matched.
+      def primary_title_info
+        doc.at_xpath("/mods:mods/mods:titleInfo[@usage='primary']", NAMESPACE) ||
+          doc.at_xpath("/mods:mods/mods:titleInfo", NAMESPACE)
+      end
+
+      # All top-level <abstract> elements (MODS permits several).
+      def abstract_nodes
+        doc.xpath("/mods:mods/mods:abstract", NAMESPACE)
+      end
+
+      # The "keyword" subjects the simple form manages: attribute-free <subject>
+      # elements whose element children are all <topic>. Anything with an
+      # authority/valueURI (or a non-topic child, e.g. a <name> subject) is curated
+      # and left untouched. (Distinct from the projection's #topical_subjects,
+      # which harvests *every* <topic> for the access copy.)
+      def keyword_subjects
+        doc.xpath("/mods:mods/mods:subject", NAMESPACE).select { |s| keyword_subject?(s) }
+      end
+
+      # Build a namespaced MODS element reusing the document's existing `mods:`
+      # namespace declaration (so new nodes never re-declare xmlns).
+      def build_node(name, text = nil)
+        node = Nokogiri::XML::Node.new(name, doc)
+        node.namespace = doc.root.namespace_definitions.find { |d| d.prefix == "mods" }
+        node.content = text unless text.nil?
+        node
+      end
+
+      private
+
+      def keyword_subject?(subject)
+        return false if subject.attributes.any?
+
+        topics = subject.element_children
+        topics.any? && topics.all? { |c| c.name == "topic" }
+      end
+    end
+  end
+end

data/lib/neu/mods/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module NEU
+  module MODS
+    # Current gem version, read from the `.version` file at the repo root at load
+    # time (mirrors the atlas_rb convention so a single `.version` bump drives the
+    # gem version + `bundler/gem_tasks` release).
+    VERSION = File.read(File.expand_path("../../../.version", __dir__)).strip
+  end
+end

data/lib/neu-mods.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "neu/mods/version"
+require_relative "neu/mods/canonicalize"
+require_relative "neu/mods/selectors"
+require_relative "neu/mods/projection"
+require_relative "neu/mods/document"
+
+# Northeastern-flavored MODS v3 projection + selection for the DRS.
+#
+# A Nokogiri-native, dependency-light *reading/projection contract* over MODS
+# documents, shared by Cerberus (front end) and Atlas (API backend). Pure
+# functions over a document -- no Rails, no persistence, no HTTP. It answers two
+# questions and nothing else:
+#
+#   * "Where is X?"            -> Selectors (live nodes; serve read AND write)
+#   * "What does this project to?" -> Projection (plain data; for index/display)
+#
+# Top-level conveniences delegate to the canonicalization helpers so callers can
+# write `NEU::MODS.whitespace_equivalent?(a, b)` etc. without reaching into the
+# submodules.
+module NEU
+  module MODS
+    # The MODS v3 namespace, as a Nokogiri xpath namespace hash.
+    NAMESPACE = { "mods" => "http://www.loc.gov/mods/v3" }.freeze
+
+    module_function
+
+    # Whitespace no-op guard (see Canonicalize).
+    def canonical_ws(str) = Canonicalize.canonical_ws(str)
+    def whitespace_equivalent?(current, incoming) = Canonicalize.whitespace_equivalent?(current, incoming)
+
+    # Curator-freetext normalization for the access copy (see TextNormalizer).
+    def normalize(str) = TextNormalizer.normalize(str)
+    def normalize_paragraphs(str) = TextNormalizer.normalize_paragraphs(str)
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: neu-mods
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Cliff
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.60'
+description: 'Nokogiri-native, dependency-light reading/projection contract over MODS
+  v3 documents, shared by the DRS front end (Cerberus) and API backend (Atlas). Pure
+  functions over a document: selectors that locate nodes (for editing) and projections
+  that return plain data (for indexing/display). No Rails, no persistence, no HTTP.'
+email:
+- d.cliff@northeastern.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .version
+- Gemfile
+- README.md
+- Rakefile
+- lib/neu-mods.rb
+- lib/neu/mods/canonicalize.rb
+- lib/neu/mods/document.rb
+- lib/neu/mods/projection.rb
+- lib/neu/mods/selectors.rb
+- lib/neu/mods/version.rb
+homepage:
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'false'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.9
+signing_key:
+specification_version: 4
+summary: Northeastern-flavored MODS XML projection + selection for the DRS.
+test_files: []