neu-mods 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89680abe072d9ece72ed12e15a8301aca55c7a8a3ec5f6ee9fb092ebd507eeac
-  data.tar.gz: d65dddefd46aa15b4408cd1ba952faf24d603edfb59b5b1b556e46ea982875d7
+  metadata.gz: 1469790b96ff15516d9766db6673159fb9ad14128e02c4399842580c198a1740
+  data.tar.gz: 97c442fbd0765c6de753bbb140da3fa2ac61fedcb63104d38801c569a876ddcd
 SHA512:
-  metadata.gz: 882dd1f0cd4f57a90d55c1c06ba67e3f5595e68fe8908eb40069d1dbf9215e72685ddf48c832ebe48b510aac1063cfe2ed251c7dc5dd06130b56fd357c432237
-  data.tar.gz: fcb62c4fe88773b8224938a35fc254a7c0eb22845e3084f257b3fa1ed8c49b95da7aa6c81d7531868cfc0d772db594bd2098884dce8f4a4bc98ea37358f359d7
+  metadata.gz: 5b2fdf0e42f5fd65fccbc732ddf4a15b3f311f4719a3a95a294517da643c8005dcbb3c25a7b3e2b1e7afcb67c1f29f9cecacf7ec157640ef3a2b2d56e13197ac
+  data.tar.gz: 4ffc16684b6176a667fcf62dadc6e20c5fed2733c1f6bdcd39df345fe6df77f5cd412f62fe879676f1075f7c690ca6cb368b6876bfca0e4a98477af8112731c2

data/.version

@@ -1 +1 @@
-0.4.0
+0.5.0

data/README.md

@@ -33,6 +33,11 @@ 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.date_created_with_precision
+                   # => [DateTime, "year"|"month"|"day"]   w3cdtf YYYY, YYYY-MM
+                   #    and YYYY-MM-DD all parse; the precision says which shape
+                   #    the record declared, so display cannot invent a month or
+                   #    a day the record never claimed
 doc.to_h           # => full projection, keyed to Atlas's Metadata::MODS attributes
 
 # Pure title composition (no document needed) — for callers that already hold

data/lib/neu/mods/projection.rb

@@ -171,32 +171,48 @@ module NEU
         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
+      # The three w3cdtf date shapes a dateCreated may stop at: year, year-month,
+      # 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.
+      W3CDTF_DATE = /\A(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?\z/
+
+      # Parsed dateCreated paired with the granularity the record declared, as
+      # [value, precision]. value is nil if no originInfo/dateCreated, or "" if
+      # present but unparseable (mirrors Atlas's safe_date_parse rescue).
+      # precision is "year", "month" or "day", and nil whenever value is not a
+      # DateTime.
+      #
+      # The precision has to be captured here, at the only point where the shape
+      # is still visible: a year-only date parses to January 1st, and no consumer
+      # downstream can tell that month and day from a record that claimed them.
+      # A preservation repository must not project a precision it was not given.
+      def date_created_with_precision
         node = doc.at_xpath("/mods:mods/mods:originInfo/mods:dateCreated", NAMESPACE)
-        return nil unless node
+        return [nil, nil] unless node
 
         str = NEU::MODS.canonical_ws(node.text)
-        return nil if str.empty?
+        return [nil, nil] if str.empty?
 
-        begin
-          DateTime.parse(str)
-        rescue Date::Error
-          ""
-        end
+        parse_w3cdtf(str)
       end
 
+      def date_created = date_created_with_precision.first
+      def date_created_precision = date_created_with_precision.last
+
       # --- 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
+        date, date_precision = date_created_with_precision
+
         {
           main_title: access_title_parts,
           names: names,
           languages: languages,
-          date_created: date_created,
+          date_created: date,
+          date_created_precision: date_precision,
           resource_type: resource_type,
           genres: genres,
           format: format,
@@ -223,6 +239,26 @@ module NEU
 
       # --- helpers -------------------------------------------------------------
 
+      # A shape-matched but impossible date (2026-13, 2026-02-30) reaches DateTime
+      # and raises; it falls to the "" sentinel like any other unparseable value.
+      # Anything outside the three shapes keeps the old permissive parse, so a
+      # timestamp still projects as a full date.
+      def parse_w3cdtf(str)
+        m = W3CDTF_DATE.match(str)
+        return [DateTime.parse(str), "day"] unless m
+
+        precision = if m[3]
+                      "day"
+                    elsif m[2]
+                      "month"
+                    else
+                      "year"
+                    end
+        [DateTime.new(m[1].to_i, (m[2] || 1).to_i, (m[3] || 1).to_i), precision]
+      rescue Date::Error
+        ["", nil]
+      end
+
       def text_at(xpath)
         node = doc.at_xpath(xpath, NAMESPACE)
         node ? NEU::MODS.canonical_ws(node.text) : ""

metadata

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