disarm 0.15.0

data/lib/disarm/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Disarm
+  # Kept in lockstep with the Rust crate / Python package version.
+  VERSION = "0.15.0"
+end

data/lib/disarm.rb

@@ -0,0 +1,618 @@
+# frozen_string_literal: true
+
+require_relative "disarm/version"
+
+# Load the native extension. Precompiled platform gems ship a per-minor-version
+# subdir (e.g. lib/disarm/3.3/disarm.so); a source gem compiles to
+# lib/disarm/disarm.so. Try the versioned path first, then fall back.
+begin
+  ruby_minor = RUBY_VERSION[/\d+\.\d+/]
+  require_relative "disarm/#{ruby_minor}/disarm"
+rescue LoadError => e
+  # Only fall back to the unversioned (source-gem) path when the versioned file
+  # is genuinely absent. A real load failure of an *existing* ext (e.g. a missing
+  # dependent shared library or an undefined symbol) must propagate, not be masked
+  # by the fallback.
+  raise unless e.message.include?("cannot load such file")
+
+  require_relative "disarm/disarm"
+end
+
+# The native extension (ext/disarm) defines the raw `_`-prefixed shims and the
+# already-idiomatic no-option methods (strip_accents, fold_case,
+# suspicious_hostname?). This file adds the idiomatic Ruby surface on top (#357):
+# keyword arguments with the core's defaults, symbol tokens (:latin, :default, …),
+# a single transliterate(text, scheme:) entrypoint, and a Disarm::Error hierarchy.
+# Each method is still a thin wrapper over the pure-Rust `disarm` core.
+module Disarm
+  # Base class for every error disarm raises, so consumers can `rescue
+  # Disarm::Error`. The native shim raises Ruby's built-in ArgumentError /
+  # RuntimeError; the wrappers below translate those into this hierarchy.
+  class Error < StandardError; end
+
+  # Raised for an invalid argument — an unknown scheme/target token, a
+  # malformed option, etc. (the core's `ErrorKind::InvalidArgument`).
+  class InvalidArgument < Error; end
+
+  class << self
+    # Transliterate Unicode text to ASCII. `scheme:` selects the standard:
+    # :default (the general-purpose scheme), :strict_iso9, or :gost7034. `lang:`
+    # applies a language profile on top of the scheme (e.g. "uk" → Київ → "Kyiv",
+    # "de" → ü → "ue"); nil means no profile. Both accept a String or Symbol.
+    def transliterate(text, scheme: :default, lang: nil)
+      scheme = scheme.to_s
+      lang = lang&.to_s
+      translate_errors do
+        # The bare default with no profile keeps the core's borrow-on-no-op fast
+        # path; any scheme or lang takes the option-carrying builder path.
+        if lang.nil? && scheme == "default"
+          _transliterate(text)
+        else
+          _transliterate_opts(text, scheme, lang)
+        end
+      end
+    end
+
+    # Fold cross-script confusables toward `target:` (:latin or :cyrillic).
+    #
+    # `digit_policy:` selects how non-Latin DIGITS fold (#561).
+    #
+    # `:numeric` (default) sends them to the ASCII digit — `०` becomes `0` — which is
+    # right for prose, where a Devanagari zero really is a zero.
+    #
+    # `:tr39` uses upstream's targets, which send most of them to a Latin letter
+    # (`०` → `o`; three of the 45 rows fold to `.` or to the two characters `rn`
+    # instead). That is what an identifier *skeleton* wants, since its only job is to
+    # make two confusable identifiers collide. The two differ on 45 rows and agree
+    # everywhere else. Scoped to `target: :latin` — the override rows are generated from
+    # the Latin table and carry TR39's Latin-script targets, so with `target: :cyrillic`
+    # it is a no-op.
+    #
+    # `:preserve` leaves the digit alone (#648). The other two both yield a mixed-script
+    # numeral — `२०२४` becomes `२0२४` or `२o२४` — so neither keeps the script. Unlike
+    # `:tr39` it applies under every target script.
+    def normalize_confusables(text, target: :latin, digit_policy: :numeric)
+      translate_errors { _normalize_confusables(text, target.to_s, digit_policy.to_s) }
+    end
+
+    # Whether `text` contains a character confusable with `target:` (:latin or
+    # :cyrillic).
+    def confusable?(text, target: :latin)
+      translate_errors { _confusable?(text, target.to_s) }
+    end
+
+    # Generate a URL-safe slug. Mirrors the core's `SlugConfig` defaults; every
+    # option past `text` is keyword-only. (`regex_pattern`/`replacements` are not
+    # surfaced yet — see ext/disarm/src/lib.rs.)
+    def slugify(
+      text,
+      separator: "-",
+      lowercase: true,
+      max_length: 0,
+      word_boundary: false,
+      save_order: false,
+      stopwords: [],
+      allow_unicode: false,
+      lang: nil,
+      entities: true,
+      decimal: true,
+      hexadecimal: true,
+      safe_chars: ""
+    )
+      translate_errors do
+        # `Array(stopwords)` tolerates the common `stopwords: nil` (and a bare
+        # String) instead of raising NoMethodError on `.map`.
+        _slugify(
+          text, separator.to_s, lowercase, max_length, word_boundary, save_order,
+          Array(stopwords).map(&:to_s), allow_unicode, lang&.to_s, entities, decimal,
+          hexadecimal, safe_chars.to_s
+        )
+      end
+    end
+
+    # Replace emoji with their plain names (e.g. "👍" → "thumbs up").
+    # `strip_modifiers:` drops skin-tone / variation modifiers before naming.
+    def demojize(text, strip_modifiers: false)
+      translate_errors { _demojize(text, strip_modifiers) }
+    end
+
+    # Canonicalize, but raise rather than silently normalize a structural difference
+    # away — the half of the pair that lets a caller reject input instead of comparing
+    # a value the sender never wrote.
+    def canonicalize_strict(text)
+      translate_errors { _canonicalize_strict(text) }
+    end
+
+    # Strip the non-interchange and invisible classes while KEEPING the script.
+    #
+    # Unlike `canonicalize` it folds no confusables, so non-Latin text survives as
+    # itself. It cannot be rebuilt from the seven universal `strip_*` methods, and the
+    # difference runs both ways: this preserves the Private Use Area (icon fonts) and
+    # keeps the VS15/VS16 presentation selectors after a base, which the naive chain
+    # deletes, and it collapses TAB/LF to a space, which the primitives leave alone.
+    def strip_format(text)
+      _strip_format(text)
+    end
+
+    # Remove obfuscation (zero-width, bidi, combining-mark abuse) while keeping
+    # legible content.
+    def strip_obfuscation(text)
+      translate_errors { _strip_obfuscation(text) }
+    end
+
+    # Canonicalize text for security-sensitive comparison: strip obfuscation,
+    # control characters, and other spoofing vectors. The name describes the
+    # mechanism (Unicode canonicalization for matching), not a safety guarantee —
+    # this is not an output sanitizer; encode at the sink.
+    #
+    # Two steps introduce ASCII, not one (#719): the leading NFKC, and the confusable
+    # fold, which reaches characters NFKC leaves alone. U+2236 RATIO becomes ":", U+2044
+    # FRACTION SLASH becomes "/", U+2216 SET MINUS becomes "\\". A string that carried no
+    # delimiter can leave here carrying one. #inspect_anomalies reports it as :confusable
+    # WHEN the word also carries an ASCII letter, which is the gate that keeps ordinary
+    # non-Latin text from firing; a delimiter-only string is not reported.
+    def canonicalize(text)
+      translate_errors { _canonicalize(text) }
+    end
+
+    # @deprecated Renamed to {#canonicalize} in 0.11 (the +_clean+ name
+    #   overpromised safety); removed in 1.0.
+    def security_clean(text)
+      warn("[disarm] security_clean is deprecated; use canonicalize (removed in 1.0)", category: :deprecated)
+      canonicalize(text)
+    end
+
+    # Case/accent/script-insensitive search lookup key. `lang:` applies a
+    # language profile for transliteration (e.g. "ru", "uk"); nil means none.
+    # Raises Disarm::InvalidArgument on an unknown lang.
+    def search_key(text, lang: nil)
+      translate_errors { _search_key(text, lang&.to_s) }
+    end
+
+    # Collation sort key (like #search_key, but keeps base accented characters
+    # for correct ordering). `lang:` applies a language profile; nil means none.
+    # Raises Disarm::InvalidArgument on an unknown lang.
+    def sort_key(text, lang: nil)
+      translate_errors { _sort_key(text, lang&.to_s) }
+    end
+
+    # Library catalog deduplication key (search_key plus confusable folding).
+    # `lang:` applies a language profile; `strict_iso9:` selects the ISO 9:1995
+    # Cyrillic scheme. Raises Disarm::InvalidArgument on an unknown lang.
+    def catalog_key(text, lang: nil, strict_iso9: false)
+      translate_errors { _catalog_key(text, lang&.to_s, strict_iso9) }
+    end
+
+    # Strip diacritics ("café" → "cafe").
+    def strip_accents(text)
+      translate_errors { _strip_accents(text) }
+    end
+
+    # Unicode case-fold ("HELLO" → "hello").
+    def fold_case(text)
+      translate_errors { _fold_case(text) }
+    end
+
+    # Whether `text` is a stable identity key under case folding — whether
+    # `fold_case` and `String#downcase` agree on it (#619). A false result means
+    # some other string folds to the same value, so a table keyed on this one can
+    # collide: "groß.txt" and "gross.txt" are the pair node-tar collided on
+    # (CVE-2026-23950). It is a fact about the string, not an accusation.
+    def case_fold_stable?(text)
+      translate_errors { _is_case_fold_stable?(text) }
+    end
+
+    # Which of `values` are the same name under `key` (#620).
+    #
+    # Every other disarm detector is a single-string predicate, and a collision is
+    # not a property of a single string — "groß.txt" is an ordinary German filename,
+    # and "аdmin" is only a problem next to "admin". This is the set-shaped question
+    # node-tar's PathReservations guard failed to ask (CVE-2026-23950).
+    #
+    # `key:` is one of "fold_case", "search_key", "catalog_key", "canonicalize",
+    # "canonicalize_strict", "normalize_confusables". There is no default: a stronger
+    # key finds more collisions, including ones nobody attacked ("search_key" collides
+    # "Muller" with "Müller"), so the choice is the policy.
+    #
+    # A group is reported only when two or more DISTINCT inputs share a key; the same
+    # name twice is the same name twice. `lang:` reaches "search_key" and
+    # "catalog_key" and is ignored by the rest.
+    #
+    # Returns an array of hashes with `:key`, `:values` (distinct, first-appearance
+    # order) and `:indices` (every position, ascending — not parallel to `:values`).
+    def find_key_collisions(values, key:, lang: nil)
+      translate_errors { _find_key_collisions(values, key.to_s, lang&.to_s) }
+        .map { |k, vals, idx| { key: k, values: vals, indices: idx } }
+    end
+
+    # Whether the hostname looks like a mixed-script / confusable / bidi-reorder
+    # IDN spoof. Flags a mixed-script label, a Latin confusable, or a
+    # bidi-direction conflict (see #bidi_conflict?, the "BiDi Swap" precondition),
+    # or a UAX #9 bidi control character (#603 — the RLO spoof, which the direction
+    # conflict is blind to).
+    # A false result asserts nothing was *found*, not that the host is safe.
+    def suspicious_hostname?(host)
+      translate_errors { _suspicious_hostname?(host) }
+    end
+
+    # The full hostname homoglyph analysis (#549) behind #suspicious_hostname?,
+    # as a Hash. `:suspicious` is a maximally conservative screen (an any-character
+    # confusable test flags essentially every non-Latin host), not a precise verdict;
+    # branch on the granular signals plus your own policy. Keys: :suspicious,
+    # :scripts, :mixed_script, :has_confusables, :bidi_conflict, :bidi_control,
+    # :has_invisible, :compat_fold, :cross_label_script,
+    # :label_scripts, :whole_script_confusable, :label_whole_script_confusable,
+    # :canonical. `:whole_script_confusable` is a graded signal, NOT folded into
+    # `:suspicious` (see #545).
+    def analyze_hostname(host, contractions: false)
+      suspicious, scripts, mixed_script, has_confusables, bidi_conflict,
+        bidi_control, has_invisible, compat_fold, cross_label_script, label_scripts,
+        whole_script_confusable, (label_whole_script_confusable, canonical) =
+        translate_errors { _analyze_hostname(host, contractions) }
+      {
+        suspicious:,
+        scripts:,
+        mixed_script:,
+        has_confusables:,
+        bidi_conflict:,
+        bidi_control:,
+        has_invisible:,
+        compat_fold:,
+        cross_label_script:,
+        label_scripts:,
+        whole_script_confusable:,
+        label_whole_script_confusable:,
+        canonical:,
+      }
+    end
+
+    # Apply a Unicode normalization form. `form:` is :nfc (default), :nfd,
+    # :nfkc, or :nfkd (a Symbol or String; case-insensitive).
+    def normalize(text, form: :nfc)
+      translate_errors { _normalize(text, form.to_s.upcase) }
+    end
+
+    # Whether `text` is already in normalization `form:` (default :nfc).
+    def normalized?(text, form: :nfc)
+      translate_errors { _normalized?(text, form.to_s.upcase) }
+    end
+
+    # Fold every run of Unicode whitespace to a single ASCII space and trim
+    # leading/trailing whitespace (#433). Folds whitespace ONLY — the line
+    # controls (TAB/LF/VT/FF/CR), the information separators (U+001C–U+001F),
+    # NEL, the Zs/Zl/Zp spaces, and the blank-rendering set (Braille blank,
+    # Hangul fillers) each fold to a single space. It does NOT delete control or
+    # zero-width characters — use `strip_control_chars` / `strip_zero_width_chars`
+    # for that. Folding the line controls (not deleting) means "a\rb" → "a b".
+    def collapse_whitespace(text)
+      translate_errors { _collapse_whitespace(text) }
+    end
+
+    # Remove C0/C1 control characters (except tab and newline).
+    def strip_control_chars(text)
+      translate_errors { _strip_control_chars(text) }
+    end
+
+    # Remove zero-width characters (ZWSP, ZWNJ, ZWJ, word joiner).
+    def strip_zero_width_chars(text)
+      translate_errors { _strip_zero_width_chars(text) }
+    end
+
+    # Remove Unicode bidirectional control characters (a homoglyph/spoof vector).
+    def strip_bidi(text)
+      translate_errors { _strip_bidi(text) }
+    end
+
+    # Strip the Unicode Tags block (U+E0000-U+E007F) - the "ASCII smuggling"
+    # channel - preserving well-formed emoji subdivision flag sequences (#413).
+    def strip_tags(text)
+      translate_errors { _strip_tags(text) }
+    end
+
+    # Strip every variation selector (VS1-VS256) - the arbitrary-byte smuggling
+    # channel (#413).
+    def strip_variation_selectors(text)
+      translate_errors { _strip_variation_selectors(text) }
+    end
+
+    # Strip every Unicode noncharacter (U+FDD0-U+FDEF and U+xFFFE/U+xFFFF) (#413).
+    def strip_noncharacters(text)
+      translate_errors { _strip_noncharacters(text) }
+    end
+
+    # Strip every Private Use Area code point (BMP and planes 15/16) (#413).
+    def strip_pua(text)
+      translate_errors { _strip_pua(text) }
+    end
+
+    # Strip "zalgo" combining-mark stacking, keeping at most `max_marks:` (2)
+    # combining marks per base character.
+    def strip_zalgo(text, max_marks: 2)
+      translate_errors { _strip_zalgo(text, max_marks) }
+    end
+
+    # Whether `text` looks like zalgo: any base character carries more than
+    # `threshold:` (3) combining marks.
+    def zalgo?(text, threshold: 3)
+      translate_errors { _zalgo?(text, threshold) }
+    end
+
+    # Number of grapheme clusters (user-perceived characters). Counts an emoji
+    # or flag as one, unlike `String#length` (code points).
+    def grapheme_len(text)
+      translate_errors { _grapheme_len(text) }
+    end
+
+    # Split `text` into an array of grapheme-cluster strings.
+    def grapheme_split(text)
+      translate_errors { _grapheme_split(text) }
+    end
+
+    # Truncate `text` to at most `max_graphemes` grapheme clusters, never cutting
+    # through the middle of a cluster.
+    def grapheme_truncate(text, max_graphemes)
+      translate_errors { _grapheme_truncate(text, max_graphemes) }
+    end
+
+    # Display width (terminal columns) of a single grapheme `cluster` by East
+    # Asian Width. Pass `ambiguous_wide: true` to treat ambiguous-width
+    # characters as 2 columns.
+    def grapheme_width(cluster, ambiguous_wide: false)
+      translate_errors { _grapheme_width(cluster, ambiguous_wide) }
+    end
+
+    # Total display width (terminal columns) of `text`.
+    def terminal_width(text, ambiguous_wide: false)
+      translate_errors { _terminal_width(text, ambiguous_wide) }
+    end
+
+    # Turn arbitrary text into a safe filename. `platform:` is :universal
+    # (default), :windows, or :posix; `preserve_extension:` keeps the final
+    # extension when truncating to `max_length:`. Raises Disarm::InvalidArgument
+    # on an unknown platform.
+    #
+    # A safe *filename*, not a safe URL path segment. "%" is legal in a filename, so one
+    # the caller typed is kept — sanitize_filename("..%2Fetc") returns "%2Fetc" — and a
+    # consumer that percent-decodes the result must validate AFTER decoding. What this
+    # will not do is manufacture one: "%" never appears in the output unless it appeared
+    # in the input (#721).
+    def sanitize_filename(text, separator: "_", max_length: 255, platform: :universal,
+                          lang: nil, preserve_extension: true)
+      translate_errors do
+        _sanitize_filename(text, separator.to_s, max_length, platform.to_s,
+                           lang&.to_s, preserve_extension)
+      end
+    end
+
+    # Reverse-transliterate Latin back to a native script. `lang:` is :el (Greek),
+    # :ru (Russian), or :uk (Ukrainian) — a Symbol or String.
+    def reverse_transliterate(text, lang:)
+      translate_errors { _reverse_transliterate(text, lang.to_s) }
+    end
+
+    # Every character in `text` with no romanization, as an array of
+    # `{ char:, offset: }` hashes (byte offset), in order of appearance.
+    # `scheme:`/`lang:` mirror #transliterate.
+    def find_untranslatable(text, scheme: :default, lang: nil)
+      translate_errors do
+        _find_untranslatable(text, scheme.to_s, lang&.to_s)
+          .map { |ch, offset| { char: ch, offset: offset } }
+      end
+    end
+
+    # Every upstream confusable source the bundled table does not fold, as a sorted
+    # Array of single-character Strings (#563). An Array rather than a Set, matching
+    # `list_scripts` and avoiding a `require "set"` in the gem entrypoint.
+    #
+    # Read as exposure, not as a score — this is where an adaptive attacker goes once
+    # the mapped sources stop working. It includes five ASCII characters ("%", "0",
+    # "1", "I", "m"): TR39 is a skeleton transform, and disarm deliberately does not
+    # apply those rows because folding a legitimate "m" to "rn" corrupts prose.
+    def unmapped_confusables(target: :latin)
+      translate_errors { _unmapped_confusables(target.to_s) }
+    end
+
+    # Confusable sources in `text` the bundled table does not fold, as an Array of
+    # `{ char:, offset: }` hashes in order of appearance — the confusables analogue of
+    # `find_untranslatable`, with the same byte-offset convention (#563).
+    def find_unmapped_confusables(text, target: :latin)
+      translate_errors do
+        _find_unmapped_confusables(text, target.to_s)
+          .map { |ch, offset| { char: ch, offset: offset } }
+      end
+    end
+
+    # ML/NLP normalization: NFKC → emoji→text → transliterate → strip accents →
+    # [case fold] → strip control → strip zero-width → collapse whitespace.
+    #
+    # `fold_case:` defaults to true. Pass false in front of a CASED model — folding is
+    # destructive, cannot be undone downstream, and an uncased evaluation harness cannot
+    # measure what it cost. It restores case, not diacritics: accents are still stripped.
+    #
+    # Folds no confusables, so it is not a homoglyph defence at any setting; compose it
+    # after `normalize_confusables` when a model needs both.
+    def ml_normalize(text, lang: nil, emoji_style: "cldr", fold_case: true)
+      translate_errors { _ml_normalize(text, lang&.to_s, emoji_style.to_s, fold_case) }
+    end
+
+    # The Unicode scripts present in `text`, in first-appearance order
+    # (Common/Inherited excluded), as stable UCD identifiers (e.g. "Latin").
+    def detect_scripts(text)
+      translate_errors { _detect_scripts(text) }
+    end
+
+    # Whether `text` mixes characters from more than one script.
+    def mixed_script?(text)
+      translate_errors { _is_mixed_script?(text) }
+    end
+
+    # Whether `text` mixes strong left-to-right and strong right-to-left
+    # characters — the precondition for Bidi display-reordering (UAX #9) and the
+    # structural signal behind "BiDi Swap"-style spoofs. Fires on the real
+    # letters (no U+202x override). A false result is not a safety guarantee.
+    def bidi_conflict?(text)
+      translate_errors { _has_bidi_conflict?(text) }
+    end
+
+    # Whether `text` carries any of the twelve UAX #9 explicit formatting characters,
+    # with no context taken into account. The counterpart to `bidi_conflict?`, which
+    # reads strong-direction letters and is blind to these; the two are disjoint. The
+    # anomaly detector's `bidi` kind reports nine of the twelve, holding back LRM, RLM
+    # and ALM because a lone directional mark is ordinary in right-to-left text.
+    def bidi_control?(text)
+      _has_bidi_control?(text)
+    end
+
+    # Explain how `lang: "auto"` detection resolves `text`: a hash with
+    # `:script`, `:chosen_lang` (both nil if undetected), `:reason`, and
+    # `:discriminators_hit`.
+    def inspect_auto_lang(text)
+      script, chosen_lang, reason, discriminators = translate_errors { _inspect_auto_lang(text) }
+      { script: script, chosen_lang: chosen_lang, reason: reason,
+        discriminators_hit: discriminators }
+    end
+
+    # Curated metadata for one language `code` (e.g. "de"), as a hash with symbol
+    # keys: `:name`, `:script`, `:region`, and `:context` ("none"/"partial"/"full").
+    # Raises Disarm::InvalidArgument on an unknown code.
+    def lang_info(code)
+      translate_errors { _lang_info(code.to_s) }
+    end
+
+    # Curated metadata for one script `name` (e.g. "Coptic"), as a hash with symbol
+    # keys: `:name`, `:default_lang` (nil when none), `:example`, and
+    # `:context_aware`. Raises Disarm::InvalidArgument on an unknown script.
+    def script_info(name)
+      translate_errors { _script_info(name.to_s) }
+    end
+
+    # The Unicode `confusables.txt` release the bundled confusable tables were folded
+    # from, e.g. "17.0.0". Not a Unicode version for the library as a whole — the
+    # case-folding and width tables track different releases (see docs/provenance.md).
+    # The UCD release disarm's normalizer implements. Not a library-wide Unicode
+    # version — the bundled tables track different releases. This is the one integrators
+    # ask about: it decides whether disarm's normalization agrees with Ruby's.
+    def unicode_version
+      _unicode_version
+    end
+
+    # Whether a key stored under an earlier release still compares equal. A monotonic
+    # counter, not a version: two artifacts reporting the same value produce the same key
+    # for the same input. Meaningless in isolation, by design.
+    def key_schema_version
+      _key_schema_version
+    end
+
+    def confusables_version
+      translate_errors { _confusables_version }
+    end
+
+    # Every script disarm knows, as stable UCD script identifiers (includes
+    # "Common"/"Inherited"), sorted by name.
+    def list_scripts
+      translate_errors { _list_scripts }
+    end
+
+    # The language codes with context-aware transliteration support, sorted by code.
+    def list_context_langs
+      translate_errors { _list_context_langs }
+    end
+
+    # Whether any whitespace token carries out-of-place characters that disguise a
+    # real word — a cross-script homoglyph, leet, segmentation, a zero-width / bidi
+    # control, or zalgo. Reports a technical fact and leaves the malicious-or-not
+    # judgement to the caller. `lexicon` is a common-word collection (Array or Set)
+    # used only by the leet and segmentation branches; it defaults to an empty list
+    # when those branches are not needed. A bare String is rejected — pass an Array
+    # or any object responding to `:each`.
+    #
+    # For repeated calls over the same word list, build a Disarm::Lexicon once and
+    # pass it here: the native HashSet is then reused rather than rebuilt per call
+    # (HAI-SDLC 6.1).
+    def has_anomalies?(text, lexicon = [])
+      translate_errors do
+        if lexicon.is_a?(Disarm::Lexicon)
+          _has_anomalies_lex(text, lexicon)
+        else
+          _has_anomalies?(text, coerce_lexicon(lexicon))
+        end
+      end
+    end
+
+    # Full anomaly analysis: a hash with `:anomalous`, `:kinds` (in first-appearance
+    # order), `:findings` (each `{ kind:, token:, start:, end:, detail:, reason: }`,
+    # with byte offsets), and `:reason` (the first finding's reason, or nil).
+    # `lexicon` defaults to an empty list; a bare String is rejected. Pass a
+    # pre-built Disarm::Lexicon to reuse the native HashSet across calls (6.1).
+    def inspect_anomalies(text, lexicon = [])
+      anomalous, kinds, findings, reason =
+        translate_errors do
+          if lexicon.is_a?(Disarm::Lexicon)
+            _inspect_anomalies_lex(text, lexicon)
+          else
+            _inspect_anomalies(text, coerce_lexicon(lexicon))
+          end
+        end
+      {
+        anomalous: anomalous,
+        kinds: kinds,
+        findings: findings.map do |kind, token, start, finish, detail, fr|
+          { kind: kind, token: token, start: start, end: finish, detail: detail, reason: fr }
+        end,
+        reason: reason,
+      }
+    end
+
+    # Build a reusable Disarm::Pipeline for a named policy `profile` (e.g.
+    # "search_index", "normalize_web_input"). The profile's steps are validated
+    # and assembled once at construction, so the returned handle can be reused
+    # across many `#process` calls without re-resolving the profile each time —
+    # the same reuse pattern as Disarm::Lexicon. Raises Disarm::InvalidArgument
+    # on an unknown profile name.
+    #
+    #   pipe = Disarm.get_pipeline("search_index")
+    #   pipe.process("Café") # => "cafe"
+    #   pipe.process("Köln") # reuse the same handle
+    #
+    # Disarm::Pipeline#process is the Rust-defined instance method on the handle.
+    def get_pipeline(profile)
+      translate_errors { _get_pipeline(profile.to_s) }
+    end
+
+    private
+
+    # Coerce a lexicon argument to an Array of Strings for the native layer.
+    # Fast-path: an Array already containing only Strings is passed through as-is.
+    # Any other Enumerable (Set, etc.) is mapped to String. A bare String is rejected
+    # with ArgumentError — callers must wrap it in an Array: ["word"].
+    def coerce_lexicon(lexicon)
+      # An explicit nil is treated as an empty lexicon (parity with the `= []`
+      # default and the other bindings' null handling), not an error.
+      return [] if lexicon.nil?
+
+      raise ::ArgumentError, "lexicon must be an Array or Enumerable, not a String" \
+        if lexicon.is_a?(::String)
+
+      return lexicon if lexicon.is_a?(::Array) && lexicon.all?(::String)
+
+      lexicon.map(&:to_s)
+    end
+
+    # Run a native call, re-raising its built-in exception as the matching
+    # Disarm::Error subclass so callers can `rescue Disarm::Error` across the
+    # whole surface. The original backtrace is preserved (passed as the third
+    # `raise` argument) so the failing native call site stays visible. A bad
+    # argument from the native layer can arrive as ArgumentError (an invalid
+    # scheme/target), TypeError (a non-String argument), or RangeError (e.g. a
+    # negative max_length) — all map to Disarm::InvalidArgument.
+    def translate_errors
+      yield
+    rescue Error
+      raise # already in our hierarchy — don't re-wrap
+    rescue ::ArgumentError, ::TypeError, ::RangeError => e
+      raise InvalidArgument, e.message, e.backtrace
+    rescue ::RuntimeError => e
+      raise Error, e.message, e.backtrace
+    end
+  end
+end