active_sanction 1.0.0

data/lib/active_sanction/countries.txt

@@ -0,0 +1,292 @@
+# ISO 3166-1 countries and territories, and the other names sanctions lists
+# write them under.
+#
+# One country per line, fields separated by `|`:
+#
+#     <alpha-2>|<alpha-3>|<ISO name>|<alias>|<alias>...
+#
+# Every field on a line resolves to that line's alpha-2 code, so `RU`, `RUS`,
+# `Russian Federation` and `Russia` are one answer. Fields are folded by the
+# same Normalizer::Form a name is folded by, which is why no line here spells
+# a casing, an accent or a punctuation mark: `Cote d'Ivoire` and `CÔTE
+# D'IVOIRE` both reach the `Côte d'Ivoire` below.
+#
+# ### Why the aliases are not optional
+#
+# The ISO name is frequently not what a publisher writes. The UN files
+# `NATIONALITY/VALUE` as free text and OFAC writes nationality into a remarks
+# sentence, so the corpus carries `Iran`, `Syria`, `North Korea` and `Russia`
+# far more often than it carries `Iran, Islamic Republic of` or `Korea,
+# Democratic People's Republic of`. A table with only the ISO names would
+# resolve almost nothing this library actually meets, and an unresolved
+# country is a nationality signal the scorer has to discard.
+#
+# Word order is part of that. Folding does not reorder tokens, so
+# `Korea, Democratic People's Republic of` and `Democratic People's Republic
+# of Korea` are two different strings and both have to be written down.
+#
+# ### What is deliberately not here
+#
+# **Demonyms.** `Russian`, `Egyptian` and `Syrian` are what a person is, not
+# where a country is, and the lists publish the country. Adding them would
+# also put `Chad` and `Chadian` a letter apart from several personal names.
+#
+# **Historical states, except where a list still uses one.** `USSR` and
+# `Soviet Union` are on RU because sanctions records written in the 1990s
+# still say so; `Zaire` is on CD and `Burma` on MM for the same reason.
+#
+# ### Collisions
+#
+# The first line that claims a spelling keeps it, so order in this file
+# decides a tie. There are none among the fields below, and the suite holds
+# the file to that -- a future addition that collides with an existing name
+# fails rather than silently changing what an existing country resolves to.
+AD|AND|Andorra
+AE|ARE|United Arab Emirates|UAE
+AF|AFG|Afghanistan
+AG|ATG|Antigua and Barbuda
+AI|AIA|Anguilla
+AL|ALB|Albania
+AM|ARM|Armenia
+AO|AGO|Angola
+AQ|ATA|Antarctica
+AR|ARG|Argentina
+AS|ASM|American Samoa
+AT|AUT|Austria
+AU|AUS|Australia
+AW|ABW|Aruba
+AX|ALA|Åland Islands
+AZ|AZE|Azerbaijan
+BA|BIH|Bosnia and Herzegovina
+BB|BRB|Barbados
+BD|BGD|Bangladesh
+BE|BEL|Belgium
+BF|BFA|Burkina Faso
+BG|BGR|Bulgaria
+BH|BHR|Bahrain
+BI|BDI|Burundi
+BJ|BEN|Benin
+BL|BLM|Saint Barthélemy
+BM|BMU|Bermuda
+BN|BRN|Brunei Darussalam|Brunei
+BO|BOL|Bolivia, Plurinational State of|Bolivia|Plurinational State of Bolivia
+BQ|BES|Bonaire, Sint Eustatius and Saba
+BR|BRA|Brazil
+BS|BHS|Bahamas|The Bahamas
+BT|BTN|Bhutan
+BV|BVT|Bouvet Island
+BW|BWA|Botswana
+BY|BLR|Belarus|Byelorussia
+BZ|BLZ|Belize
+CA|CAN|Canada
+CC|CCK|Cocos (Keeling) Islands|Keeling Islands
+CD|COD|Congo, Democratic Republic of the|Democratic Republic of the Congo|DR Congo|Zaire|Congo (Democratic Republic)
+CF|CAF|Central African Republic
+CG|COG|Congo|Republic of the Congo|Congo-Brazzaville
+CH|CHE|Switzerland
+CI|CIV|Côte d'Ivoire|Ivory Coast
+CK|COK|Cook Islands
+CL|CHL|Chile
+CM|CMR|Cameroon
+CN|CHN|China|People's Republic of China
+CO|COL|Colombia
+CR|CRI|Costa Rica
+CU|CUB|Cuba
+CV|CPV|Cabo Verde|Cape Verde
+CW|CUW|Curaçao
+CX|CXR|Christmas Island
+CY|CYP|Cyprus
+CZ|CZE|Czechia|Czech Republic
+DE|DEU|Germany|Federal Republic of Germany
+DJ|DJI|Djibouti
+DK|DNK|Denmark
+DM|DMA|Dominica
+DO|DOM|Dominican Republic
+DZ|DZA|Algeria
+EC|ECU|Ecuador
+EE|EST|Estonia
+EG|EGY|Egypt|Arab Republic of Egypt
+EH|ESH|Western Sahara
+ER|ERI|Eritrea
+ES|ESP|Spain
+ET|ETH|Ethiopia
+FI|FIN|Finland
+FJ|FJI|Fiji
+FK|FLK|Falkland Islands|Malvinas
+FM|FSM|Micronesia, Federated States of|Micronesia|Federated States of Micronesia
+FO|FRO|Faroe Islands
+FR|FRA|France
+GA|GAB|Gabon
+GB|GBR|United Kingdom|United Kingdom of Great Britain and Northern Ireland|Great Britain|England|Scotland|Wales|Northern Ireland
+GD|GRD|Grenada
+GE|GEO|Georgia
+GF|GUF|French Guiana
+GG|GGY|Guernsey
+GH|GHA|Ghana
+GI|GIB|Gibraltar
+GL|GRL|Greenland
+GM|GMB|Gambia|The Gambia
+GN|GIN|Guinea
+GP|GLP|Guadeloupe
+GQ|GNQ|Equatorial Guinea
+GR|GRC|Greece
+GS|SGS|South Georgia and the South Sandwich Islands
+GT|GTM|Guatemala
+GU|GUM|Guam
+GW|GNB|Guinea-Bissau
+GY|GUY|Guyana
+HK|HKG|Hong Kong
+HM|HMD|Heard Island and McDonald Islands
+HN|HND|Honduras
+HR|HRV|Croatia
+HT|HTI|Haiti
+HU|HUN|Hungary
+ID|IDN|Indonesia
+IE|IRL|Ireland
+IL|ISR|Israel
+IM|IMN|Isle of Man
+IN|IND|India
+IO|IOT|British Indian Ocean Territory
+IQ|IRQ|Iraq|Republic of Iraq
+IR|IRN|Iran, Islamic Republic of|Iran|Islamic Republic of Iran
+IS|ISL|Iceland
+IT|ITA|Italy
+JE|JEY|Jersey
+JM|JAM|Jamaica
+JO|JOR|Jordan
+JP|JPN|Japan
+KE|KEN|Kenya
+KG|KGZ|Kyrgyzstan
+KH|KHM|Cambodia
+KI|KIR|Kiribati
+KM|COM|Comoros
+KN|KNA|Saint Kitts and Nevis|St Kitts and Nevis
+KP|PRK|Korea, Democratic People's Republic of|Democratic People's Republic of Korea|North Korea|DPRK|Democratic People's Republic of Korea (North Korea)
+KR|KOR|Korea, Republic of|Republic of Korea|South Korea
+KW|KWT|Kuwait
+KY|CYM|Cayman Islands
+KZ|KAZ|Kazakhstan
+LA|LAO|Lao People's Democratic Republic|Laos
+LB|LBN|Lebanon
+LC|LCA|Saint Lucia|St Lucia
+LI|LIE|Liechtenstein
+LK|LKA|Sri Lanka
+LR|LBR|Liberia
+LS|LSO|Lesotho
+LT|LTU|Lithuania
+LU|LUX|Luxembourg
+LV|LVA|Latvia
+LY|LBY|Libya|Libyan Arab Jamahiriya
+MA|MAR|Morocco
+MC|MCO|Monaco
+MD|MDA|Moldova, Republic of|Moldova|Republic of Moldova
+ME|MNE|Montenegro
+MF|MAF|Saint Martin
+MG|MDG|Madagascar
+MH|MHL|Marshall Islands
+MK|MKD|North Macedonia|Macedonia|Republic of North Macedonia|The former Yugoslav Republic of Macedonia
+ML|MLI|Mali
+MM|MMR|Myanmar|Burma
+MN|MNG|Mongolia
+MO|MAC|Macao|Macau
+MP|MNP|Northern Mariana Islands
+MQ|MTQ|Martinique
+MR|MRT|Mauritania
+MS|MSR|Montserrat
+MT|MLT|Malta
+MU|MUS|Mauritius
+MV|MDV|Maldives
+MW|MWI|Malawi
+MX|MEX|Mexico
+MY|MYS|Malaysia
+MZ|MOZ|Mozambique
+NA|NAM|Namibia
+NC|NCL|New Caledonia
+NE|NER|Niger
+NF|NFK|Norfolk Island
+NG|NGA|Nigeria
+NI|NIC|Nicaragua
+NL|NLD|Netherlands|The Netherlands|Holland
+NO|NOR|Norway
+NP|NPL|Nepal
+NR|NRU|Nauru
+NU|NIU|Niue
+NZ|NZL|New Zealand
+OM|OMN|Oman
+PA|PAN|Panama
+PE|PER|Peru
+PF|PYF|French Polynesia
+PG|PNG|Papua New Guinea
+PH|PHL|Philippines
+PK|PAK|Pakistan
+PL|POL|Poland
+PM|SPM|Saint Pierre and Miquelon
+PN|PCN|Pitcairn
+PR|PRI|Puerto Rico
+PS|PSE|Palestine, State of|Palestine|State of Palestine|Palestinian Territory|Occupied Palestinian Territory|Occupied Palestinian Territories|Palestinian
+PT|PRT|Portugal
+PW|PLW|Palau
+PY|PRY|Paraguay
+QA|QAT|Qatar
+RE|REU|Réunion
+RO|ROU|Romania
+RS|SRB|Serbia
+RU|RUS|Russian Federation|Russia|USSR|Soviet Union
+RW|RWA|Rwanda
+SA|SAU|Saudi Arabia
+SB|SLB|Solomon Islands
+SC|SYC|Seychelles
+SD|SDN|Sudan
+SE|SWE|Sweden
+SG|SGP|Singapore
+SH|SHN|Saint Helena, Ascension and Tristan da Cunha|Saint Helena
+SI|SVN|Slovenia
+SJ|SJM|Svalbard and Jan Mayen
+SK|SVK|Slovakia|Slovak Republic
+SL|SLE|Sierra Leone
+SM|SMR|San Marino
+SN|SEN|Senegal
+SO|SOM|Somalia
+SR|SUR|Suriname
+SS|SSD|South Sudan
+ST|STP|Sao Tome and Principe
+SV|SLV|El Salvador
+SX|SXM|Sint Maarten
+SY|SYR|Syrian Arab Republic|Syria
+SZ|SWZ|Eswatini|Swaziland
+TC|TCA|Turks and Caicos Islands
+TD|TCD|Chad
+TF|ATF|French Southern Territories
+TG|TGO|Togo
+TH|THA|Thailand
+TJ|TJK|Tajikistan
+TK|TKL|Tokelau
+TL|TLS|Timor-Leste|East Timor
+TM|TKM|Turkmenistan
+TN|TUN|Tunisia
+TO|TON|Tonga
+TR|TUR|Türkiye|Turkey
+TT|TTO|Trinidad and Tobago
+TV|TUV|Tuvalu
+TW|TWN|Taiwan, Province of China|Taiwan
+TZ|TZA|Tanzania, United Republic of|Tanzania|United Republic of Tanzania
+UA|UKR|Ukraine
+UG|UGA|Uganda
+UM|UMI|United States Minor Outlying Islands
+US|USA|United States|United States of America|America
+UY|URY|Uruguay
+UZ|UZB|Uzbekistan
+VA|VAT|Holy See|Vatican City|Vatican
+VC|VCT|Saint Vincent and the Grenadines|St Vincent
+VE|VEN|Venezuela, Bolivarian Republic of|Venezuela|Bolivarian Republic of Venezuela
+VG|VGB|Virgin Islands, British|British Virgin Islands
+VI|VIR|Virgin Islands, U.S.|United States Virgin Islands
+VN|VNM|Viet Nam|Vietnam
+VU|VUT|Vanuatu
+WF|WLF|Wallis and Futuna
+WS|WSM|Samoa
+YE|YEM|Yemen
+YT|MYT|Mayotte
+ZA|ZAF|South Africa
+ZM|ZMB|Zambia
+ZW|ZWE|Zimbabwe

data/lib/active_sanction/country.rb

@@ -0,0 +1,164 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/normalizer/form"
+
+module ActiveSanction
+  # Which country a publisher meant, as an ISO 3166-1 alpha-2 code.
+  #
+  #   ActiveSanction::Country.code("Russia")               # => "RU"
+  #   ActiveSanction::Country.code("RUS")                  # => "RU"
+  #   ActiveSanction::Country.code("Russian Federation")   # => "RU"
+  #   ActiveSanction::Country.code("Ruritania")            # => nil
+  #
+  #   ActiveSanction::Country.name("RU")                   # => "Russian Federation"
+  #
+  # ### Why the scorer cannot compare these as strings
+  #
+  # Nationality is the one identifier on these records that is published as
+  # prose. A caller screening a customer has an ISO code in a database column;
+  # the UN files `NATIONALITY/VALUE` as whatever its Committee wrote, and OFAC
+  # writes nationality into the middle of a remarks sentence. So a query of
+  # `RU` meets a record of `Russian Federation`, and a query of `Iran` meets
+  # `Iran, Islamic Republic of`.
+  #
+  # Compared as strings those are three disagreements, and a scorer that reads
+  # a disagreement as a conflict does not merely fail to boost the match -- it
+  # *penalizes* it, on exactly the records where the caller supplied the most
+  # information. That is the worst shape a false negative can take, so the
+  # comparison happens on a resolved code or it does not happen at all: see
+  # Scorer::Adjustments, which treats an unresolvable country as absent rather
+  # than as a conflict.
+  #
+  # ### What resolution is, and what it is not
+  #
+  # A lookup, not a guess. Every spelling in `countries.txt` -- the alpha-2,
+  # the alpha-3, the ISO name and the aliases a list actually writes -- is
+  # folded once at load and mapped to its alpha-2 code, and a string that is
+  # not in that table returns nil. There is no fuzzy matching here on purpose:
+  # `Niger` and `Nigeria` are two countries, `Guinea` is three, and a scorer
+  # that resolved a country approximately would be applying a decisive
+  # adjustment on a guess.
+  #
+  # Input is folded by the same `Normalizer::Form` names are folded by, which
+  # is what makes `côte d'ivoire`, `Cote D Ivoire` and `CÔTE-D'IVOIRE` one
+  # lookup. It is folded with no stoplist: a country is not an entity, and the
+  # organization lists would take `Republic` out of half this table.
+  #
+  # ### The table is a data file
+  #
+  # `lib/active_sanction/countries.txt`, one country per line, for the reason
+  # the normalizer's dictionaries are files: what belongs on it is settled by
+  # reading government lists rather than by reading Ruby, and a contributor
+  # adding the spelling their market uses should be sending a one-line diff.
+  module Country
+    extend T::Sig
+
+    # @api private
+    TABLE = T.let(File.expand_path("countries.txt", __dir__), String)
+
+    # `<alpha-2>|<alpha-3>|<ISO name>|<alias>...`
+    #
+    # @api private
+    SEPARATOR = T.let("|", String)
+
+    class << self
+      extend T::Sig
+
+      # The alpha-2 code for a name, a code or an alias, or nil for anything
+      # not in the table. nil and blank are nil rather than an error: an
+      # absent nationality is the common case on these lists, and the scorer
+      # asks about it record by record.
+      sig { params(value: T.untyped).returns(T.nilable(String)).checked(:tests) }
+      def code(value)
+        return nil if value.nil?
+
+        key = fold(value.to_s)
+        key.empty? ? nil : CODES[key]
+      end
+
+      # The ISO name for an alpha-2 code, for a hit a person has to read. The
+      # ISO name rather than the alias a publisher wrote, deliberately: the
+      # published string is still on the record, and an explanation that names
+      # one country two ways is one a reviewer has to reconcile.
+      sig { params(value: T.untyped).returns(T.nilable(String)).checked(:tests) }
+      def name(value)
+        found = code(value)
+        found && NAMES[found]
+      end
+
+      # Every alpha-2 code in the table, in file order.
+      sig { returns(T::Array[String]).checked(:tests) }
+      def codes = NAMES.keys
+
+      # The fold a lookup key goes through. Public because a collision in the
+      # table is a fact about folded strings rather than about the file, and
+      # the suite checks for one.
+      sig { params(value: String).returns(String).checked(:tests) }
+      def fold(value) = Normalizer::Form.new(value).value
+
+      # Reads the shipped table, or another one shaped like it. Returns the
+      # pair the constants below hold: spelling => alpha-2, and alpha-2 =>
+      # ISO name.
+      #
+      # A spelling claimed twice raises rather than resolving to whichever
+      # line came first. Two countries quietly sharing a name would move a
+      # nationality adjustment onto the wrong record, and it would do it
+      # silently -- the table would still load and every lookup would still
+      # answer.
+      sig { params(path: String).returns([T::Hash[String, String], T::Hash[String, String]]).checked(:tests) }
+      def read(path = TABLE)
+        codes = {}
+        names = {}
+        each_row(path) do |fields|
+          alpha2 = T.must(fields.first)
+          names[alpha2] = fields[2]
+          fields.each { |field| claim(codes, field, alpha2) }
+        end
+        [codes.freeze, names.freeze]
+      end
+
+      private
+
+      # One country per line; blank lines and `#` comments ignored, as in the
+      # normalizer's dictionaries.
+      sig { params(path: String, block: T.proc.params(fields: T::Array[String]).void).void }
+      def each_row(path, &block)
+        File.readlines(path, chomp: true).each do |line|
+          row = line.strip
+          next if row.empty? || row.start_with?("#")
+
+          fields = row.split(SEPARATOR).map(&:strip).reject(&:empty?)
+          raise InvalidArgument, "#{path}: a country needs a code, a code and a name: #{row.inspect}" if fields.size < 3
+
+          block.call(fields)
+        end
+      end
+
+      sig { params(codes: T::Hash[String, String], field: String, alpha2: String).void }
+      def claim(codes, field, alpha2)
+        key = fold(field)
+        return if key.empty?
+
+        claimed = codes[key]
+        if claimed && claimed != alpha2
+          raise InvalidArgument, "#{field.inspect} is claimed by both #{claimed} and #{alpha2}"
+        end
+
+        codes[key] = alpha2
+      end
+    end
+
+    # Built at load rather than memoized on first use, so nothing has to
+    # synchronize reading a file. Private because the two readers above are
+    # the way to reach them.
+    codes, names = read
+    # @api private
+    CODES = T.let(codes, T::Hash[String, String])
+    # @api private
+    NAMES = T.let(names, T::Hash[String, String])
+    private_constant :CODES, :NAMES
+  end
+end

data/lib/active_sanction/deprecation.rb

@@ -0,0 +1,168 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module ActiveSanction
+  # How this library says that something it still supports is going away.
+  #
+  #   ActiveSanction::Deprecation.warn(
+  #     "ActiveSanction.screen(name:)",
+  #     replacement: "ActiveSanction.screen(Query.new(...))",
+  #     since: "1.4.0"
+  #   )
+  #   # => active_sanction: ActiveSanction.screen(name:) is deprecated since
+  #   #    1.4.0 and will be removed in 1.6.0. Use
+  #   #    ActiveSanction.screen(Query.new(...)) instead.
+  #   #    Called from app/jobs/screen_job.rb:31
+  #
+  # The rules that message is stating are in `docs/api_stability.md`: a
+  # deprecated thing keeps working for one full minor release after the one
+  # that deprecated it, and the removal version is computed from `since`
+  # rather than chosen, so nobody has to remember the policy to apply it.
+  #
+  # ### Ruby's own switch, rather than one of ours
+  #
+  # This routes through `Kernel#warn` with `category: :deprecated`, so a host
+  # silences it with `Warning[:deprecated] = false` -- the same line that
+  # silences every other deprecation in their process, and the line they
+  # already have if they run a quiet suite. A `config.deprecation_mode` of our
+  # own would be one more thing to discover, and it would not be the thing
+  # already sitting in their `spec_helper`.
+  #
+  # Ruby's default for that switch is off outside verbose mode. That is
+  # deliberate on Ruby's part and it is kept: the audience for a deprecation
+  # is a developer running `ruby -w`, a test suite or a CI build, and a
+  # warning a production process cannot act on is a log line nobody reads.
+  #
+  # ### Once per call site, not once per call
+  #
+  # A deprecated method called while looping over 19,000 records would
+  # otherwise write 19,000 identical lines. The first call from each source
+  # location warns and the rest are silent. `reset!` clears that memory, which
+  # is what a spec asserting a deprecation needs and what nothing else should
+  # touch.
+  module Deprecation
+    extend T::Sig
+
+    # Deprecations overlap for one full minor release. Something deprecated in
+    # 1.4.0 goes on working through all of 1.5.x and may be removed in 1.6.0,
+    # so an application upgrading one minor at a time always meets the warning
+    # at least one release before the breakage.
+    #
+    # @api private
+    OVERLAP_MINORS = 2
+
+    # Frames to walk past when working out who called a deprecated thing. Two
+    # of these would lie: this file is never the answer, and neither is the
+    # rest of `lib/` -- a deprecated method's own body is the frame directly
+    # beneath the warning, and reporting it would point every deprecation at
+    # this library rather than at the line a host has to change.
+    #
+    # sorbet-runtime is the third, and it is why this is a list rather than a
+    # `caller_locations(1, 1)`. Every signed method is called through a
+    # validation wrapper, so the immediate caller of anything in `lib/` is
+    # Sorbet's `call_validation.rb` -- and that wrapper *moves* once Sorbet
+    # swaps in its fast path, so a call site read naively is not even stable
+    # between two calls from the same line, which silently defeats the
+    # per-site memory above.
+    #
+    # @api private
+    INTERNAL_PATHS = T.let(
+      [File.expand_path("..", __dir__),
+       Gem.loaded_specs["sorbet-runtime"]&.full_gem_path].compact.freeze,
+      T::Array[String]
+    )
+
+    @seen = T.let({}, T::Hash[String, TrueClass])
+    @mutex = T.let(Mutex.new, Mutex)
+
+    class << self
+      extend T::Sig
+
+      # @param subject [String] what is deprecated, written the way a caller
+      #   writes it -- a method signature, a constant, a configuration setting.
+      # @param since [String] the released version that deprecated it.
+      # @param replacement [String, nil] what to use instead. Nil says there is
+      #   nothing to move to, which is worth saying out loud rather than
+      #   leaving somebody to search for one that does not exist.
+      # @param removal [String, nil] the version it may be removed in.
+      #   Computed from `since` when omitted, which is the case that should be
+      #   normal -- a hand-written removal version is a policy exception, and
+      #   an exception is worth having to type.
+      # @return [void]
+      sig do
+        params(subject: String, since: String, replacement: T.nilable(String),
+               removal: T.nilable(String)).void
+      end
+      def warn(subject, since:, replacement: nil, removal: nil)
+        return unless Warning[:deprecated]
+
+        site = call_site
+        return unless first_time?("#{subject}@#{site}")
+
+        Kernel.warn(message(subject, since, replacement, removal, site), category: :deprecated)
+      end
+
+      # The version something deprecated in `since` may be removed in: the
+      # minor after the next one. A patch release never removes anything, so
+      # the patch component is dropped rather than carried forward.
+      #
+      # @param since [String] the version that deprecated it
+      # @return [String] the earliest version it may be removed in
+      sig { params(since: String).returns(String) }
+      def removal_for(since)
+        major, minor = since.split(".").first(2).map(&:to_i)
+        "#{major}.#{T.must(minor) + OVERLAP_MINORS}.0"
+      end
+
+      # Forget which call sites have already warned. For a spec that asserts a
+      # deprecation fires; nothing in a running application should call it.
+      #
+      # @return [void]
+      sig { void }
+      def reset!
+        @mutex.synchronize { @seen.clear }
+      end
+
+      private
+
+      # The first frame outside this library, which is the line a host would
+      # have to change. Says so plainly rather than naming a frame it does not
+      # believe.
+      sig { returns(String) }
+      def call_site
+        caller_locations(2, 32)&.each do |location|
+          path = location.path
+          # Evaluated code has no path, and is not a line anybody can edit.
+          next if path.nil?
+          next if INTERNAL_PATHS.any? { |internal| path.start_with?(internal) }
+
+          return "#{path}:#{location.lineno}"
+        end
+        "an unknown location"
+      end
+
+      sig { params(key: String).returns(T::Boolean) }
+      def first_time?(key)
+        @mutex.synchronize do
+          next false if @seen.key?(key)
+
+          @seen[key] = true
+        end
+      end
+
+      sig do
+        params(subject: String, since: String, replacement: T.nilable(String),
+               removal: T.nilable(String), site: String).returns(String)
+      end
+      def message(subject, since, replacement, removal, site)
+        parts = ["active_sanction: #{subject} is deprecated since #{since} " \
+                 "and will be removed in #{removal || removal_for(since)}."]
+        parts << "Use #{replacement} instead." if replacement
+        parts << "Called from #{site}"
+        parts.join(" ")
+      end
+    end
+  end
+end