seaports 1.0.0

data/lib/seaports/builder.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "csv"
+require "json"
+
+require_relative "../seaports"
+
+module Seaports
+  # Rebuilds the shipped sea-port table from a published UN/LOCODE code list.
+  #
+  # The table is generated, not hand-maintained, and this is the only thing
+  # that should ever write it — so a refresh is `rake seaports:refresh` against
+  # a newer UNECE release rather than a diff someone edits by hand.
+  #
+  # UNECE's own distribution is a zip of headerless latin-1 CSVs, so the source
+  # here is the datasets/un-locode mirror, which republishes the same list with
+  # headers, UTF-8 and a machine-readable release number. It is a third party,
+  # which is why every refresh runs through Seaports::Diff before anything
+  # ships.
+  #
+  # Nothing breaks if a release is skipped: a port missing from our copy falls
+  # back to whatever the caller rendered before the table existed.
+  class Builder
+    SOURCE_URL = "https://raw.githubusercontent.com/datasets/un-locode/main/data/code-list.csv"
+    DATAPACKAGE_URL = "https://raw.githubusercontent.com/datasets/un-locode/main/datapackage.json"
+
+    HEADERS = %w[locode name lat lng].freeze
+
+    # The published list, straight off the network — or off disk, if what was
+    # handed over is a path. Both, because a rebuild from an already-downloaded
+    # release is how this is debugged, and it should not need a different
+    # entry point. Kept separate from parsing so every other path through this
+    # class can be tested with a string.
+    def self.fetch(source = SOURCE_URL)
+      return File.read(source) if File.exist?(source)
+
+      require "open-uri"
+      URI.parse(source).read
+    end
+
+    # Which UN/LOCODE edition the mirror is currently publishing, as UNECE
+    # names it: "2024.2.0" upstream becomes "2024-2" here. Nil rather than a
+    # guess if the mirror changes shape — a wrong release number is worse than
+    # an absent one, because it would be believed.
+    def self.published_release(source = DATAPACKAGE_URL)
+      version = JSON.parse(fetch(source))["version"].to_s
+      match = version.match(/\A(\d{4})\.(\d)/)
+      match && "#{match[1]}-#{match[2]}"
+    rescue StandardError
+      nil
+    end
+
+    def initialize(source)
+      @source = source
+    end
+
+    # [locode, name, lat, lng] per port, deduplicated and sorted by locode.
+    # Sorted because the file is committed: a stable order means a refresh
+    # diff shows what changed rather than the whole table moving.
+    def rows
+      @rows ||= CSV.parse(@source, headers: true)
+        .select { |row| seaport?(row) }
+        .map { |row| port_row(row) }
+        .uniq { |locode, *| locode }
+        .sort_by(&:first)
+    end
+
+    def write(path = Seaports::TABLE_PATH)
+      CSV.open(path, "w") do |csv|
+        csv << HEADERS
+        rows.each { |row| csv << row }
+      end
+      path
+    end
+
+    def located_count
+      rows.count { |row| !row[2].nil? }
+    end
+
+    private
+
+    # UNECE classifies every entry by function, and position 1 of that string
+    # is "port" — the only one a vessel can call at. Keeping the other 98k
+    # entries would mean a road terminal or a postal exchange could answer a
+    # lookup for a ship's port call, which is worse than not answering at all.
+    #
+    # `Change` marks an entry's fate in the current release; "X" is one being
+    # removed, and those are dropped.
+    def seaport?(row)
+      row["Function"].to_s.include?("1") &&
+        !row["Change"].to_s.include?("X") &&
+        !row["Location"].to_s.strip.empty? &&
+        !row["Name"].to_s.strip.empty?
+    end
+
+    def port_row(row)
+      lat, lng = decimal_degrees(row["Coordinates"])
+      ["#{row['Country']}#{row['Location']}".upcase, row["Name"].strip, lat, lng]
+    end
+
+    # UNECE writes coordinates as "2421N 11812E" — degrees and whole minutes,
+    # zero-padded, no separator. Rounded to four places, which is metres: the
+    # source only resolves to a minute (about a mile), and writing more digits
+    # than that would dress a coarse figure up as a survey.
+    def decimal_degrees(value)
+      match = value.to_s.strip.match(/\A(\d{2})(\d{2})([NS])\s+(\d{3})(\d{2})([EW])\z/)
+      return [nil, nil] if match.nil?
+
+      lat = (match[1].to_i + (match[2].to_i / 60.0)) * (match[3] == "S" ? -1 : 1)
+      lng = (match[4].to_i + (match[5].to_i / 60.0)) * (match[6] == "W" ? -1 : 1)
+      [lat.round(4), lng.round(4)]
+    end
+  end
+end

data/lib/seaports/diff.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module Seaports
+  # What a refresh actually changed, and whether it is safe to ship.
+  #
+  # The failure mode worth designing for is not "we missed a port". It is a bad
+  # upstream release — a truncated file, a changed column, a mirror that
+  # rebuilt itself wrong — landing in a gem that thousands of lookups trust. A
+  # human reading a pull request cannot eyeball 17,000 rows, so the gates below
+  # are the reading, and the summary is what is left to judge.
+  class Diff
+    # Ports large enough that their disappearance means the source broke, not
+    # that the world changed. Spread across continents so a regional truncation
+    # cannot slip through, and every one of them is a port a tracking feed
+    # names on an ordinary day.
+    ANCHORS = %w[
+      AEJEA AUBNE BEANR CNSGH CNXMG COCTG DEHAM ESALG ESVLC GBFXT
+      HKHKG KRPUS NLRTM NZTRG SGSIN USLAX
+    ].freeze
+
+    # Codes that must stay out. PAPCN is the Panama Canal, which UNECE files as
+    # an unverified road terminal — see the note in Seaports. If a future
+    # release reclassifies it as a port, that should be a decision someone
+    # makes, not a row that appears quietly.
+    EXCLUDED = %w[PAPCN].freeze
+
+    MINIMUM_COUNT = 15_000
+
+    # A real UNECE release adds and retires a handful of entries. Losing two
+    # percent of the table in one go is a broken source, not a busy half-year.
+    MAXIMUM_SHRINKAGE = 0.02
+
+    def self.between(before_path, after_path)
+      new(read(before_path), read(after_path))
+    end
+
+    def self.read(path)
+      CSV.foreach(path, headers: true).each_with_object({}) do |row, ports|
+        locode = row["locode"].to_s.strip.upcase
+        next if locode.empty?
+
+        ports[locode] = { name: row["name"].to_s.strip, point: point(row) }
+      end
+    end
+
+    def self.point(row)
+      lat = row["lat"].to_s.strip
+      lng = row["lng"].to_s.strip
+      return nil if lat.empty? || lng.empty?
+
+      [lat.to_f, lng.to_f]
+    end
+
+    def initialize(before, after)
+      @before = before
+      @after = after
+    end
+
+    def changed?
+      !(added.empty? && removed.empty? && renamed.empty? && repositioned.empty?)
+    end
+
+    def added
+      @added ||= (@after.keys - @before.keys).sort
+    end
+
+    def removed
+      @removed ||= (@before.keys - @after.keys).sort
+    end
+
+    # [locode, was, now] for a port that kept its code and changed its name.
+    def renamed
+      @renamed ||= common.filter_map do |locode|
+        was = @before[locode][:name]
+        now = @after[locode][:name]
+        [locode, was, now] if was != now
+      end
+    end
+
+    # Every kind of position change in one list, tagged, because they read
+    # differently downstream: a port that gains coordinates puts a new marker
+    # on a map, and one that loses them takes a marker away. Both are worth
+    # seeing before a release, and neither is a failure.
+    def repositioned
+      @repositioned ||= common.filter_map do |locode|
+        was = @before[locode][:point]
+        now = @after[locode][:point]
+        next if was == now
+
+        [locode, @after[locode][:name], (was.nil? ? :located : (now.nil? ? :unlocated : :moved))]
+      end
+    end
+
+    # Empty means the refresh may ship. Anything here is a reason it may not,
+    # written the way it should read in an issue.
+    def failures
+      [count_failure, shrinkage_failure, *anchor_failures, *excluded_failures].compact
+    end
+
+    def ok?
+      failures.empty?
+    end
+
+    def summary
+      [
+        headline,
+        failures.empty? ? nil : "**Blocked**\n\n#{failures.map { |line| "- #{line}" }.join("\n")}",
+        section("Removed", removed.map { |locode| "`#{locode}` #{@before[locode][:name]}" }, limit: nil),
+        section("Added", added.map { |locode| "`#{locode}` #{@after[locode][:name]}" }),
+        section("Renamed", renamed.map { |locode, was, now| "`#{locode}` #{was} → #{now}" }),
+        section("Coordinates", repositioned.map { |locode, name, kind| "`#{locode}` #{name} — #{POSITION_WORDS.fetch(kind)}" })
+      ].compact.join("\n\n")
+    end
+
+    POSITION_WORDS = {
+      located: "position published for the first time",
+      unlocated: "position withdrawn",
+      moved: "position moved"
+    }.freeze
+
+    # The one-line version, for a changelog entry that should not carry four
+    # hundred bullet points.
+    def headline
+      "#{@after.size} sea ports (#{@before.size} before): " \
+        "#{added.size} added, #{removed.size} removed, " \
+        "#{renamed.size} renamed, #{repositioned.size} repositioned."
+    end
+
+    private
+
+    def common
+      @common ||= (@before.keys & @after.keys).sort
+    end
+
+    def count_failure
+      return nil if @after.size >= MINIMUM_COUNT
+
+      "Only #{@after.size} ports in the rebuilt table, below the floor of #{MINIMUM_COUNT}."
+    end
+
+    def shrinkage_failure
+      return nil if @before.empty?
+
+      shrinkage = (@before.size - @after.size).to_f / @before.size
+      return nil if shrinkage <= MAXIMUM_SHRINKAGE
+
+      "The table shrank by #{(shrinkage * 100).round(1)}%, past the #{(MAXIMUM_SHRINKAGE * 100).round}% limit."
+    end
+
+    def anchor_failures
+      ANCHORS.reject { |locode| @after.key?(locode) }
+        .map { |locode| "`#{locode}` is gone, and a port that large does not disappear." }
+    end
+
+    def excluded_failures
+      EXCLUDED.select { |locode| @after.key?(locode) }
+        .map { |locode| "`#{locode}` is now classified as a sea port upstream, which is a decision to make deliberately." }
+    end
+
+    # Removals are listed in full — they are the changes that break a caller.
+    # Everything else is capped, because a release that adds four hundred ports
+    # should not bury the four that were taken away.
+    def section(title, lines, limit: 40)
+      return nil if lines.empty?
+
+      shown = limit.nil? ? lines : lines.first(limit)
+      body = shown.map { |line| "- #{line}" }.join("\n")
+      body += "\n- …and #{lines.size - shown.size} more" if lines.size > shown.size
+      "**#{title}** (#{lines.size})\n\n#{body}"
+    end
+  end
+end

data/lib/seaports/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Seaports
+  VERSION = "1.0.0"
+
+  # The UN/LOCODE edition the shipped table was built from. UNECE republishes
+  # twice a year and names each release by year and half — "2024-2" is the
+  # second release of 2024. A gem version says what the code does; this says
+  # how old the data is, which is the question a caller actually has.
+  DATA_RELEASE = "2024-2"
+end

data/lib/seaports.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "csv"
+
+require_relative "seaports/version"
+
+# UN/LOCODE sea ports: a locode in, a port name and position out.
+#
+# Tracking feeds speak in codes. A provider names some port calls and sends
+# only a code for others, so a stop that mattered arrives as a bare "XMG" — a
+# real, load-bearing fact about a voyage written in a vocabulary nobody reads.
+# UNECE publishes the table that turns it back into "Xiamen Pt", and publishes
+# coordinates alongside, so one dataset answers both "where is this?" and
+# "where do I draw it?".
+#
+# The table ships inside the gem rather than being fetched: it is reference
+# data that changes twice a year, and a port name should not depend on a
+# network. `rake seaports:refresh` regenerates it; nothing else should write it.
+#
+#   Seaports.find("CNXMG")         # => #<data Seaports::Port locode="CNXMG", ...>
+#   Seaports.name("AUBNE")         # => "Brisbane"
+#   Seaports.coordinates("AUBNE")  # => { "lat" => -27.4667, "lng" => 153.0167 }
+#
+# Coverage is sea ports only, which is what a vessel's port call is, and
+# UNECE's own classification decides what counts. The notable absence is
+# PAPCN, "Panama Canal", which some feeds do send: UNECE files it as a road
+# terminal with status RL — "recognised location", its weakest, meaning no
+# national authority has approved it and its functions were never verified.
+# That is the default bucket for an unchecked entry rather than a ruling, but
+# the substance holds anyway, because a canal is a waterway and not a port. The
+# ports at either end are coded properly (PABLB Balboa, PACTB Cristóbal), so a
+# canal transit is better rendered from the country than from a port lookup.
+#
+# Keeping the filter narrow also guards anyone rebuilding a five-character
+# locode from a three-character carrier code, which is a heuristic: a code that
+# is not a locode tail could pair with a country to form a valid-looking locode
+# for some inland village, and a table of ports is far less likely to name it.
+module Seaports
+  TABLE_PATH = File.expand_path("../data/un_locode_seaports.csv", __dir__)
+
+  Port = Data.define(:locode, :name, :coordinates)
+
+  class << self
+    # Nil for anything the table does not hold, which callers must handle:
+    # ~17k ports is most of the world's, not all of it, and an unknown code is
+    # the ordinary case rather than an error.
+    def find(locode)
+      key = normalize(locode)
+      return nil if key.nil?
+
+      table[key]
+    end
+
+    def name(locode)
+      find(locode)&.name
+    end
+
+    # { "lat" => Float, "lng" => Float }, or nil. String keys because the usual
+    # destination is JSON on its way to a map. Roughly a third of the table has
+    # no coordinates published, so a named port with no position is normal.
+    def coordinates(locode)
+      find(locode)&.coordinates
+    end
+
+    # Every port in the table, ordered by locode. Materialised on each call
+    # rather than handed out from the cache, so a caller cannot mutate the
+    # table everyone else reads.
+    def all
+      table.values.dup
+    end
+
+    # How many ports the table holds — the guard that a truncated or
+    # half-written CSV is caught by a test rather than by a production page.
+    def count
+      table.size
+    end
+
+    # Which UN/LOCODE edition the shipped table came from, for a caller that
+    # wants to assert its data is not years old.
+    def data_release
+      DATA_RELEASE
+    end
+
+    private
+
+    # A locode is five characters: a two-letter country and a three-character
+    # place. Anything else is not one, and guessing at it would mean answering
+    # a question that was not asked.
+    def normalize(locode)
+      key = locode.to_s.strip.upcase
+      key.match?(/\A[A-Z]{2}[A-Z0-9]{3}\z/) ? key : nil
+    end
+
+    # Read once, on the first lookup rather than at require time: most
+    # processes never look a port up, and the ones that do can afford the parse.
+    def table
+      @table || LOAD_LOCK.synchronize { @table ||= load_table }
+    end
+
+    LOAD_LOCK = Mutex.new
+
+    def load_table
+      CSV.foreach(TABLE_PATH, headers: true).each_with_object({}) do |row, ports|
+        locode = normalize(row["locode"])
+        next if locode.nil? || blank?(row["name"])
+
+        ports[locode] = Port.new(locode: locode, name: row["name"], coordinates: point(row))
+      end
+    end
+
+    def point(row)
+      return nil if blank?(row["lat"]) || blank?(row["lng"])
+
+      { "lat" => row["lat"].to_f, "lng" => row["lng"].to_f }
+    end
+
+    def blank?(value)
+      value.to_s.strip.empty?
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: seaports
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Édouard Brière
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+description: |
+  Every sea port UNECE publishes a UN/LOCODE for, as a lookup table with no
+  dependencies and no network calls. Turns the bare codes in an AIS or
+  carrier tracking feed back into port names and coordinates. The table is
+  regenerated from each UN/LOCODE release and shipped inside the gem.
+email:
+- edouard.briere@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- data/un_locode_seaports.csv
+- lib/seaports.rb
+- lib/seaports/builder.rb
+- lib/seaports/diff.rb
+- lib/seaports/version.rb
+homepage: https://github.com/Trackberry/seaports
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Trackberry/seaports
+  changelog_uri: https://github.com/Trackberry/seaports/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Trackberry/seaports/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'UN/LOCODE sea ports: a locode in, a port name and position out.'
+test_files: []