active_sanction 1.0.0

data/lib/active_sanction/parsers/xml_records.rb

@@ -0,0 +1,140 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "set"
+require "active_sanction/parsers/format"
+require "active_sanction/parsers/xml_records/record"
+require "active_sanction/parsers/xml_records/builder"
+require "active_sanction/parsers/xml_records/backends"
+require "active_sanction/parsers/xml_records/reader"
+
+module ActiveSanction
+  module Parsers
+    # Reads a record-oriented XML list -- the UN, Canada, the EU and the UK all
+    # publish one -- into records an adapter can map onto Entities.
+    #
+    # A table is a description of the document, built once and reused for every
+    # sync; a Reader is one pass over one payload.
+    #
+    #   UN = ActiveSanction::Parsers::XmlRecords.new(records: %w[INDIVIDUAL ENTITY])
+    #
+    #   reader = UN.read(bytes)
+    #   reader.each do |record|
+    #     record.name                        # => "INDIVIDUAL"
+    #     record["FIRST_NAME"]               # => "ERIC"
+    #     record.values("NATIONALITY/VALUE") # => ["Chad"]
+    #     record.nodes("INDIVIDUAL_ALIAS")   # => [Record, ...]
+    #   end
+    #   reader.root["dateGenerated"]         # the publisher's own version marker
+    #
+    # ### Streaming from day one, before anything needs it
+    #
+    # Every list this gem launches with is small: the UN is 2.2 MB, Canada is
+    # 2.9 MB, and either would load into a DOM without anyone noticing. The one
+    # that is coming does not. OFAC's `SDN_ADVANCED.XML` is 126 MB, and a DOM
+    # design would meet it by being rewritten.
+    #
+    # So the interface is record-at-a-time now, while it is free to be: the
+    # parser holds one record's depth on a stack and drops it as soon as the
+    # adapter is done with it. What that buys is not speed, it is that the
+    # adapter written against this today is the adapter that reads a 126 MB
+    # file later, unchanged.
+    #
+    # ### Naming the records, and only the records
+    #
+    # A document's scaffolding -- `<CONSOLIDATED_LIST>`, `<INDIVIDUALS>` -- is
+    # skipped entirely rather than being built into nodes nobody asked for.
+    # Naming several record elements is normal: the UN files people under
+    # `<INDIVIDUAL>` and organizations under `<ENTITY>`, in one document, and
+    # an adapter wants a single pass over both.
+    #
+    # ### Namespaces
+    #
+    # Element and attribute names are matched with any prefix removed, so a
+    # publisher adding an `xmlns` next quarter does not silently stop matching.
+    # See Backends.local_name for why the prefix is dropped rather than
+    # resolved.
+    class XmlRecords
+      extend T::Sig
+      include Format
+
+      # Raised by a backend when the payload stops being XML. Caught by Reader,
+      # which decides between salvaging the records already read and refusing
+      # the payload outright; it escapes as a ParseError either way, so a
+      # caller rescuing the toolkit's errors does not have to know about it.
+      #
+      # `line` is ParseError's, and is nil where the backend reports no
+      # position -- libxml2 does not always.
+      class MalformedDocument < ParseError; end
+
+      # A Set: `record?` is asked once per element in the document, which for
+      # the UN is roughly 30,000 times a pass.
+      sig { returns(T::Set[String]) }
+      attr_reader :records
+
+      sig { override.returns(T::Array[String]) }
+      attr_reader :nulls
+
+      sig { override.returns(Encoding) }
+      attr_reader :encoding
+
+      # `null:` is here for the same reason DelimitedTable has it -- a
+      # publisher that writes a sentinel where it means nothing -- though the
+      # XML lists mostly use an empty element instead, which is already nil.
+      #
+      # `backend:` overrides the configured default for this table alone. Most
+      # adapters should not pass it: which XML library parses a list is an
+      # installation's decision, not a list's. See Backends.
+      sig { params(records: T.untyped, null: T.untyped, encoding: T.untyped, backend: T.untyped).void }
+      def initialize(records:, null: nil, encoding: DEFAULT_ENCODING, backend: nil)
+        @records = T.let(records!(records), T::Set[String])
+        @nulls = T.let(nulls!(null), T::Array[String])
+        @encoding = T.let(encoding!(encoding), Encoding)
+        @backend = T.let(backend&.to_sym, T.nilable(Symbol))
+        freeze
+      end
+
+      # A pass over one payload. Takes the bytes as a String, which is what
+      # Sources::Base hands #parse.
+      sig { params(payload: T.untyped).returns(Reader) }
+      def read(payload) = Reader.new(table: self, payload: payload)
+
+      # Whether an element name starts a record. Asked by every backend for
+      # every element outside a record, so it stays a Set lookup.
+      sig { params(name: String).returns(T::Boolean) }
+      def record?(name) = records.include?(name)
+
+      # The record element names in declaration order, for a message or an
+      # inspect -- Set is the right shape to ask `record?` of and the wrong
+      # shape to print.
+      sig { returns(T::Array[String]) }
+      def record_names = records.to_a
+
+      # Resolved per call rather than at construction, so a table built at
+      # class-definition time -- which is where an adapter builds it -- still
+      # honours an `xml_backend` set later in an initializer.
+      sig { returns(T.untyped) }
+      def backend = Backends.resolve(@backend || ActiveSanction.config.xml_backend)
+
+      sig { returns(String) }
+      def inspect
+        "#<#{self.class} records=#{record_names.join(", ")}#{" null=#{nulls.first.inspect}" if nulls.any?}>"
+      end
+
+      private
+
+      # Accepts one element name or several. Stored as a Set: a document with
+      # 1,011 records asks `record?` once per element in the file, which for
+      # the UN is roughly 30,000 times.
+      sig { params(value: T.untyped).returns(T::Set[String]) }
+      def records!(value)
+        names = Array(value).map { |name| -name.to_s.strip }.reject(&:empty?).uniq
+        raise InvalidArgument, "records must name at least one element, e.g. records: \"INDIVIDUAL\"" if names.empty?
+
+        Set.new(names).freeze
+      end
+    end
+  end
+end

data/lib/active_sanction/parsers.rb

@@ -0,0 +1,94 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/error"
+
+module ActiveSanction
+  # The format toolkits adapters parse with. A source declares what its file
+  # looks like -- delimiter, column names, null sentinel -- and gets rows back;
+  # what those rows *mean* stays in the adapter, because that is the part no
+  # two publishers agree on.
+  #
+  # Nothing here knows about Entity. These are file readers, and keeping them
+  # ignorant of the canonical model is what lets an adapter for a list nobody
+  # here has seen reuse them.
+  module Parsers
+    # A payload that could not be read at all: the wrong format, a truncated
+    # download, an encoding that cannot be decoded. Distinct from a Warning,
+    # which is a *row* that could not be read while the rest of the file could.
+    #
+    # The same class as ActiveSanction::ParseError, under the name the toolkits
+    # raise it by. It is declared with the rest of the public hierarchy rather
+    # than here because a caller rescuing "this list could not be read" should
+    # not have to know which of these toolkits read it -- and because a source
+    # adapter parsing a format none of them covers raises the same thing.
+    ParseError = ActiveSanction::ParseError
+
+    # One row the parser could not use, kept rather than raised.
+    #
+    # A sanctions list is not a file we control. OFAC ships 19,321 rows and a
+    # single unbalanced quote somewhere in the middle must not cost the other
+    # 19,320 -- refusing to load a list because one record is malformed fails
+    # exactly when the list is most needed. So a bad row is recorded here and
+    # skipped, and the caller decides whether the count is tolerable.
+    #
+    # `line` is the line number within the file, which is what makes a warning
+    # actionable: a 5.6 MB CSV is only debuggable if the complaint says where.
+    # It is nil when the parser cannot say -- libxml2 reports no position for a
+    # record -- and a warning that cannot point at a line still says what went
+    # wrong rather than pointing at the wrong one.
+    class Warning
+      extend T::Sig
+
+      # nil when the parser cannot say which line -- see above.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :line
+
+      sig { returns(String) }
+      attr_reader :message
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :snippet
+
+      sig { params(line: T.nilable(Integer), message: String, snippet: T.untyped).void }
+      def initialize(line:, message:, snippet: nil)
+        @line = T.let(line, T.nilable(Integer))
+        @message = T.let(message, String)
+        @snippet = T.let(snippet.nil? ? nil : truncate(snippet), T.nilable(String))
+        freeze
+      end
+
+      sig { returns(String) }
+      def to_s
+        "#{"line #{line}: " if line}#{message}#{" -- #{snippet.inspect}" if snippet}"
+      end
+
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def to_h = { line: line, message: message, snippet: snippet }
+
+      sig { returns(String) }
+      def inspect = "#<#{self.class} #{self}>"
+
+      private
+
+      # A malformed row is frequently malformed because it is enormous -- an
+      # unclosed quote swallows everything after it -- so the evidence is
+      # trimmed before it is kept.
+      sig { params(text: T.untyped).returns(String) }
+      def truncate(text)
+        string = text.to_s
+        -(string.length > 120 ? "#{string[0, 120]}..." : string)
+      end
+    end
+  end
+end
+
+require "active_sanction/parsers/column_shape"
+require "active_sanction/parsers/delimited_table"
+require "active_sanction/parsers/spreadsheet"
+require "active_sanction/parsers/xml_records"
+require "active_sanction/parsers/xml_records/backends/rexml"
+require "active_sanction/parsers/xml_records/backends/nokogiri"
+require "active_sanction/parsers/join"

data/lib/active_sanction/partial_date/parser.rb

@@ -0,0 +1,124 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "date"
+
+module ActiveSanction
+  class PartialDate
+    # Reads the date expressions the lists publish in free text. OFAC ships
+    # dates inside a remarks blob ("DOB circa 1962"), so the vocabulary here is
+    # whatever a government typist actually wrote, not a format we chose.
+    #
+    # Returns nil on anything it cannot read, per the issue: a birth date is one
+    # field on a record, and an unanticipated string should not abort the import
+    # of the entity around it. Callers decide whether that is worth reporting.
+    #
+    # @api private
+    module Parser
+      extend T::Sig
+
+      # "Sept" is not in Date::ABBR_MONTHNAMES but appears in OFAC free text.
+      MONTHS = T.let(
+        [Date::MONTHNAMES, Date::ABBR_MONTHNAMES].each_with_object({ "sept" => 9 }) do |names, months|
+          names.each_with_index { |name, number| months[name.downcase] = number if name }
+        end.freeze,
+        T::Hash[String, Integer]
+      )
+
+      ISO = T.let(/\A(\d{4})(?:-(\d{1,2})(?:-(\d{1,2}))?)?\z/, Regexp)
+      DAY_MONTH_YEAR = T.let(/\A(\d{1,2})\s+([a-z]+)\.?,?\s+(\d{4})\z/i, Regexp)
+      MONTH_DAY_YEAR = T.let(/\A([a-z]+)\.?\s+(\d{1,2})(?:st|nd|rd|th)?,?\s+(\d{4})\z/i, Regexp)
+      MONTH_YEAR = T.let(/\A([a-z]+)\.?,?\s+(\d{4})\z/i, Regexp)
+      APPROXIMATE = T.let(/\A(?:circa|approximately|approx|about|ca|c)\.?\s+|\A~\s*/i, Regexp)
+      BETWEEN = T.let(/\Abetween\s+/i, Regexp)
+      WORD_RANGE = T.let(/\A(.+?)\s+(?:to|and|through|until)\s+(.+)\z/i, Regexp)
+      # A bare dash separates a span only between two four-digit years. Anything
+      # looser would read the "-" in 1972-04 as a span from 1972 to April.
+      YEAR_RANGE = T.let(/\A(\d{4})\s*[-–—]\s*(\d{4})\z/, Regexp)
+
+      # An XML Schema `xs:date` may carry a UTC offset, and the UN publishes
+      # nine of its listing dates that way: "2015-07-01-04:00". The offset
+      # records which midnight a clerk was working against, not which day the
+      # listing is, so it is trimmed rather than applied -- shifting a listing
+      # date across a day boundary to honour a timezone the publisher never
+      # meant would be a worse answer than ignoring it. Without this the whole
+      # date reads as nil and nine listings silently lose their date.
+      ZONE = T.let(/(?<=\d)(?:Z|[+-]\d{2}:\d{2})\z/, Regexp)
+
+      module_function
+
+      sig { params(text: T.untyped).returns(T.nilable(PartialDate)) }
+      def call(text)
+        string = text.to_s.strip.squeeze(" ").sub(ZONE, "")
+        return nil if string.empty?
+
+        approximate = APPROXIMATE.match?(string)
+        string = string.sub(APPROXIMATE, "").sub(BETWEEN, "")
+        span(string, approximate) || point(string, approximate)
+      end
+
+      # Endpoints go back through .call, so "1971 to circa 1973" reads. A nested
+      # span raises in the constructor and comes back as nil.
+      sig { params(string: String, approximate: T::Boolean).returns(T.nilable(PartialDate)) }
+      def span(string, approximate)
+        match = WORD_RANGE.match(string) || YEAR_RANGE.match(string)
+        return nil unless match
+
+        from = call(match[1])
+        to = call(match[2])
+        return nil if from.nil? || to.nil?
+
+        build(from: from, to: to, approximate: approximate)
+      end
+
+      sig { params(string: String, approximate: T::Boolean).returns(T.nilable(PartialDate)) }
+      def point(string, approximate)
+        attributes = point_attributes(string)
+        return nil if attributes.nil?
+
+        build(**attributes, approximate: approximate)
+      end
+
+      # A shape the regexes accept can still be an impossible date -- 31
+      # February 1972 -- and that is the constructor's judgment, not ours.
+      sig { params(attributes: T.untyped).returns(T.nilable(PartialDate)) }
+      def build(**attributes)
+        PartialDate.new(**attributes)
+      rescue ArgumentError
+        nil
+      end
+
+      sig { params(string: String).returns(T.nilable(T::Hash[Symbol, T.nilable(Integer)])) }
+      def point_attributes(string)
+        match = ISO.match(string)
+        return { year: match[1].to_i, month: match[2]&.to_i, day: match[3]&.to_i } if match
+
+        worded_attributes(string)
+      end
+
+      sig { params(string: String).returns(T.nilable(T::Hash[Symbol, T.nilable(Integer)])) }
+      def worded_attributes(string)
+        if (match = DAY_MONTH_YEAR.match(string))
+          named_month(year: match[3], month: match[2], day: match[1])
+        elsif (match = MONTH_DAY_YEAR.match(string))
+          named_month(year: match[3], month: match[1], day: match[2])
+        elsif (match = MONTH_YEAR.match(string))
+          named_month(year: match[2], month: match[1])
+        end
+      end
+
+      sig do
+        params(year: T.untyped, month: T.untyped, day: T.untyped)
+          .returns(T.nilable(T::Hash[Symbol, T.nilable(Integer)]))
+      end
+      def named_month(year:, month:, day: nil)
+        number = MONTHS[month.downcase]
+        return nil if number.nil?
+
+        { year: year.to_i, month: number, day: day&.to_i }
+      end
+    end
+  end
+end

data/lib/active_sanction/partial_date.rb

@@ -0,0 +1,303 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "date"
+require "active_sanction/partial_date/parser"
+
+module ActiveSanction
+  # A date a sanctions list published imprecisely. `Date` cannot hold one:
+  # collapsing "1972" to 1972-01-01 invents a precision the publisher never
+  # claimed, and a scorer that believes it will call 1972 and 1972-04-29 a
+  # conflict when they are in fact a match.
+  #
+  #   PartialDate.parse("1972")                     # year only
+  #   PartialDate.parse("circa 1962")               # approximate
+  #   PartialDate.parse("between 1971 and 1973")    # a span
+  #   PartialDate.new(year: 1965, month: 4, day: 29)
+  #
+  # Every instance carries a first and last possible date, which is what makes
+  # #overlaps? and #conflicts_with? exact regardless of how precise either side
+  # is. Instances are frozen on construction and compare by value.
+  class PartialDate
+    extend T::Sig
+
+    # :range is a precision in the sense the scorer (#32) cares about -- how
+    # much of the calendar a date could be -- not a grammatical one.
+    PRECISIONS = T.let(%i[year month day range].freeze, T::Array[Symbol])
+
+    # Canonical member order. Snapshot (#8) checksums the serialized form, so
+    # #to_h must lay its keys out the same way every time. `precision` is
+    # derived rather than stored: a stored copy can disagree with the fields it
+    # describes, and then two records that mean the same thing checksum apart.
+    #
+    # @api private
+    MEMBERS = T.let(%i[year month day from to approximate].freeze, T::Array[Symbol])
+
+    # "Circa 1962" and "1963" are the same claim about a person, made by two
+    # governments with different sources. Comparing an approximate date on its
+    # literal bounds would call that a conflict and penalize a true match, so
+    # comparison -- and only comparison, never #to_h or #to_s -- widens an
+    # approximate date by a year on each side.
+    #
+    # @api private
+    APPROXIMATE_SLACK_YEARS = 1
+
+    # A point date carries year/month/day and no endpoints; a range carries its
+    # endpoints and no year of its own. Which is which is #range?.
+    sig { returns(T.nilable(Integer)) }
+    attr_reader :year
+
+    sig { returns(T.nilable(Integer)) }
+    attr_reader :month
+
+    sig { returns(T.nilable(Integer)) }
+    attr_reader :day
+
+    sig { returns(T.nilable(PartialDate)) }
+    attr_reader :from
+
+    sig { returns(T.nilable(PartialDate)) }
+    attr_reader :to
+
+    sig { returns(T::Boolean) }
+    attr_reader :approximate
+
+    # The two dates that bound this one, whatever shape it is -- which is what
+    # makes #overlaps? exact regardless of how precise either side is. Never
+    # nil: #initialize derives both for every instance it will build.
+    sig { returns(Date) }
+    attr_reader :first_date
+
+    sig { returns(Date) }
+    attr_reader :last_date
+
+    # Reads a date expression from free text, returning nil on anything it
+    # cannot read. The vocabulary lives in Parser, which is where new source
+    # spellings get added.
+    sig { params(text: T.untyped).returns(T.nilable(PartialDate)) }
+    def self.parse(text)
+      Parser.call(text)
+    end
+
+    # Rebuilds a date from #to_h output. Accepts string keys, so a record that
+    # has been through JSON round-trips without a separate coercion step.
+    sig { params(hash: T.untyped).returns(T.attached_class) }
+    def self.from_h(hash)
+      attributes = hash.to_h.transform_keys(&:to_sym)
+      unknown = attributes.keys - MEMBERS
+      raise InvalidArgument, "unknown PartialDate attribute(s): #{unknown.join(", ")}" if unknown.any?
+
+      new(**attributes)
+    end
+
+    # A span, from the UN's `TYPE_OF_DATE = BETWEEN`. Endpoints may be
+    # PartialDates, #to_h hashes, or strings this class can parse.
+    sig { params(from: T.untyped, to: T.untyped, approximate: T::Boolean).returns(T.attached_class) }
+    def self.range(from, to, approximate: false)
+      new(from: from, to: to, approximate: approximate)
+    end
+
+    # Untyped on purpose, and the same choice Entity makes: these arrive as
+    # whatever a publisher wrote and a parser made of it. What comes back out
+    # is typed -- see the readers above.
+    sig do
+      params(year: T.untyped, month: T.untyped, day: T.untyped, from: T.untyped, to: T.untyped,
+             approximate: T.untyped).void
+    end
+    def initialize(year: nil, month: nil, day: nil, from: nil, to: nil, approximate: false)
+      @approximate = T.let(approximate ? true : false, T::Boolean)
+      @year = T.let(nil, T.nilable(Integer))
+      @month = T.let(nil, T.nilable(Integer))
+      @day = T.let(nil, T.nilable(Integer))
+      @from = T.let(nil, T.nilable(PartialDate))
+      @to = T.let(nil, T.nilable(PartialDate))
+      # Both branches assign the members they own and hand back the pair of
+      # dates that bound them, which is what makes those two non-nil for every
+      # instance rather than for most of them.
+      first, last =
+        if from.nil? && to.nil?
+          assign_point(year, month, day)
+        else
+          reject_mixed_shape(year, month, day)
+          assign_range(from, to)
+        end
+      @first_date = T.let(first, Date)
+      @last_date = T.let(last, Date)
+      freeze
+    end
+
+    sig { returns(T::Boolean) }
+    def range? = !from.nil?
+
+    sig { returns(T::Boolean) }
+    def approximate? = approximate
+
+    sig { returns(Symbol) }
+    def precision
+      return :range if range?
+      return :day if day
+      return :month if month
+
+      :year
+    end
+
+    # Every date this could be, which is the whole point of the type.
+    sig { returns(T::Range[Date]) }
+    def to_range = first_date..last_date
+
+    # True when the two dates could describe the same day. Precision does not
+    # have to match: a year-only date overlaps every full date inside it, which
+    # is what lets #32 treat 1972 against 1972-04-29 as a moderate boost rather
+    # than a miss.
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def overlaps?(other)
+      return false if other.nil?
+
+      mine = comparison_range
+      theirs = comparable!(other).comparison_range
+      mine.first <= theirs.last && theirs.first <= mine.last
+    end
+
+    # The strict complement of #overlaps? for two known dates. A missing date
+    # is not a conflict -- nobody claimed anything to contradict -- so nil
+    # answers false to both questions.
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def conflicts_with?(other)
+      return false if other.nil?
+
+      !overlaps?(other)
+    end
+
+    # Widened by APPROXIMATE_SLACK_YEARS when the publisher said circa.
+    sig { returns(T::Range[Date]) }
+    def comparison_range
+      return to_range unless approximate?
+
+      first_date.prev_year(APPROXIMATE_SLACK_YEARS)..last_date.next_year(APPROXIMATE_SLACK_YEARS)
+    end
+
+    sig { returns(T::Hash[Symbol, T.untyped]) }
+    def to_h
+      { year: year, month: month, day: day, from: from&.to_h, to: to&.to_h, approximate: approximate }
+    end
+
+    # Renders in a form .parse reads back, so a date survives a trip through
+    # free text -- which is how OFAC publishes them in the first place.
+    sig { returns(String) }
+    def to_s
+      text = range? ? "#{from} to #{to}" : point_to_s
+      approximate? ? "circa #{text}" : text
+    end
+
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def ==(other)
+      return false unless other.instance_of?(self.class)
+
+      to_h == other.to_h
+    end
+    alias eql? ==
+
+    sig { returns(Integer) }
+    def hash
+      [self.class, to_h].hash
+    end
+
+    sig { returns(String) }
+    def inspect
+      "#<#{self.class} #{self} precision=#{precision.inspect}>"
+    end
+
+    private
+
+    sig { params(year: T.untyped, month: T.untyped, day: T.untyped).returns([Date, Date]) }
+    def assign_point(year, month, day)
+      raise InvalidArgument, "year is required" if year.nil?
+
+      number = integer!(:year, year)
+      @year = number
+      @month = optional_integer(:month, month)
+      @day = optional_integer(:day, day)
+      validate_point!(number)
+      first = Date.new(number, @month || 1, @day || 1).freeze
+      # A year-only date runs to 31 December, a month to its own real last day.
+      [first, @day ? first : Date.new(number, @month || 12, -1).freeze]
+    end
+
+    sig { params(year: Integer).void }
+    def validate_point!(year)
+      raise InvalidArgument, "day given without a month" if @day && @month.nil?
+      raise InvalidArgument, "not a real date: #{to_s.inspect}" unless Date.valid_date?(year, @month || 1, @day || 1)
+    end
+
+    sig { params(from: T.untyped, to: T.untyped).returns([Date, Date]) }
+    def assign_range(from, to)
+      raise InvalidArgument, "a range needs both from and to" if from.nil? || to.nil?
+
+      first = endpoint!(:from, from)
+      last = endpoint!(:to, to)
+      @from = first
+      @to = last
+      raise InvalidArgument, "range runs backwards: #{first} to #{last}" if first.first_date > last.last_date
+
+      [first.first_date, last.last_date]
+    end
+
+    sig { params(year: T.untyped, month: T.untyped, day: T.untyped).void }
+    def reject_mixed_shape(year, month, day)
+      return if [year, month, day].all?(&:nil?)
+
+      raise InvalidArgument, "a range carries its year in its endpoints, not alongside them"
+    end
+
+    # Endpoints are themselves PartialDates so a span between two year-only
+    # dates keeps both years, and they may not nest: "between (1971 to 1972)
+    # and 1973" is not something any list publishes.
+    sig { params(member: Symbol, value: T.untyped).returns(PartialDate) }
+    def endpoint!(member, value)
+      date = coerce_endpoint(value)
+      raise InvalidArgument, "#{member} is not a date: #{value.inspect}" if date.nil?
+      raise InvalidArgument, "#{member} cannot itself be a range" if date.range?
+
+      date
+    end
+
+    sig { params(value: T.untyped).returns(T.nilable(PartialDate)) }
+    def coerce_endpoint(value)
+      case value
+      when PartialDate then value
+      when Hash then PartialDate.from_h(value)
+      else PartialDate.parse(value)
+      end
+    end
+
+    sig { params(other: T.untyped).returns(PartialDate) }
+    def comparable!(other)
+      return other if other.is_a?(PartialDate)
+
+      raise InvalidArgument, "expected a #{self.class}, got #{other.class}"
+    end
+
+    sig { params(member: Symbol, value: T.untyped).returns(T.nilable(Integer)) }
+    def optional_integer(member, value)
+      value.nil? ? nil : integer!(member, value)
+    end
+
+    sig { params(member: Symbol, value: T.untyped).returns(Integer) }
+    def integer!(member, value)
+      Integer(value.to_s, 10)
+    rescue TypeError, ArgumentError
+      raise InvalidArgument, "#{member} is not a number: #{value.inspect}"
+    end
+
+    sig { returns(String) }
+    def point_to_s
+      case precision
+      when :day then format("%<year>04d-%<month>02d-%<day>02d", year: year, month: month, day: day)
+      when :month then format("%<year>04d-%<month>02d", year: year, month: month)
+      else format("%<year>04d", year: year)
+      end
+    end
+  end
+end