disarm 0.15.0 → 0.17.0

package/disarm.linux-x64-gnu.node

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/disarm.linux-x64-gnu.node
-size: 38284256 bytes
-sha256: 28e2e707186cda676b6a0bd466b88270a9894568a9809883924fc101baf7bce3
+size: 40558392 bytes
+sha256: 9b9fa65e17615962ffc13a7279596b24597ea6f9db079abf32bdcb19d9ae7ba1

package/index.d.ts

@@ -1,6 +1,6 @@
-import { Lexicon, Pipeline } from './binding';
-import type { Untranslatable, UnmappedConfusable, AutoLangInspection, KeyCollision, LangMeta, ScriptMeta, Finding as NativeFinding, AnomalyReport as NativeAnomalyReport, HostnameAnalysis as NativeHostnameAnalysis } from './binding';
-export type { Untranslatable, UnmappedConfusable, AutoLangInspection, KeyCollision, LangMeta, ScriptMeta, };
+import { Lexicon as NativeLexicon, Pipeline } from './binding';
+import type { Untranslatable, UnmappedConfusable, AutoLangInspection, KeyCollision, LangMeta, ScriptMeta, ConfusableCoverage, Finding as NativeFinding, AnomalyReport as NativeAnomalyReport, HostnameAnalysis as NativeHostnameAnalysis } from './binding';
+export type { Untranslatable, UnmappedConfusable, AutoLangInspection, KeyCollision, LangMeta, ScriptMeta, ConfusableCoverage, };
 /** Findings from {@link analyzeHostname}. `suspicious` is a maximally
  * conservative screen, not a precise verdict (#549). */
 export type HostnameAnalysis = NativeHostnameAnalysis;
@@ -9,8 +9,13 @@ export type HostnameAnalysis = NativeHostnameAnalysis;
  * `inspectAnomalies` rebuild an internal set from the caller's word array on
  * every call; constructing a `Lexicon` once (`new Lexicon([...])`) and passing
  * it instead builds that set a single time and reuses it across calls.
+ *
+ * A thin subclass of the native handle, so a bad argument to the constructor throws a
+ * {@link DisarmError} like every other entry point (`formal/bindings`, N2).
  */
-export { Lexicon };
+export declare class Lexicon extends NativeLexicon {
+    constructor(words: string[]);
+}
 /**
  * A reusable, opaque named-policy-profile pipeline handle (#404). Build it once
  * with {@link getPipeline} for a named profile, then apply it to any number of
@@ -25,7 +30,7 @@ export { Lexicon };
  */
 export { Pipeline };
 /** The anomaly branch that fired for a finding. */
-export type AnomalyKind = 'invisible' | 'bidi' | 'bidi_mixed' | 'zalgo' | 'mixed_script' | 'leet' | 'segmentation' | 'control' | 'compat_fold' | 'confusable' | 'enclosing_mark' | 'mixed_numbers' | 'duplicate_mark';
+export type AnomalyKind = 'invisible' | 'bidi' | 'bidi_mixed' | 'zalgo' | 'mixed_script' | 'leet' | 'segmentation' | 'control' | 'compat_fold' | 'confusable' | 'enclosing_mark' | 'mixed_numbers' | 'duplicate_mark' | 'deletion' | 'smuggled';
 /**
  * One reason a token is anomalous. Re-typed over the generated {@link NativeFinding}
  * so `kind` is the {@link AnomalyKind} string-union rather than a bare `string`.
@@ -47,14 +52,17 @@ export declare class DisarmInvalidArgument extends DisarmError {
 }
 /** Transliteration scheme: the general-purpose default, ISO 9-style ASCII, or GOST R 7.0.34. */
 export type Scheme = 'default' | 'strict_iso9' | 'gost7034';
-/** Confusable-folding target script. */
-export type TargetScript = 'latin' | 'cyrillic';
+/**
+ * Confusable-folding target script. `'arabic'` and `'hebrew'` fold toward those scripts
+ * (#792); the runtime accepted them before this type admitted them.
+ */
+export type TargetScript = 'latin' | 'cyrillic' | 'arabic' | 'hebrew';
 /**
  * How the fold treats non-Latin digits.
  *
  * `'numeric'` (default) sends them to the ASCII digit — `०` becomes `0` — which is right
  * for prose. `'tr39'` uses upstream's targets, which send most of them to a Latin letter
- * (`०` → `o`), and that is what an identifier *skeleton* wants. The two differ on 45 rows.
+ * (`०` → `o`), and that is what an identifier *skeleton* wants. The two differ on 47 rows.
  *
  * Three of those rows do not land on a letter: `٠` and `۰` fold to `.`, and `𑣣` folds to
  * the two characters `rn`. A skeleton feeding a label- or path-shaped key has to allow
@@ -80,19 +88,36 @@ export interface TransliterateOptions {
     /** A language profile applied on top of the scheme (e.g. `'uk'`, `'de'`, or `'auto'`). */
     lang?: string;
 }
-/** Romanize Unicode text to ASCII. */
+/** Romanize Unicode text to ASCII. An unknown `lang` throws {@link DisarmInvalidArgument}. */
 export declare function transliterate(text: string, options?: TransliterateOptions): string;
 /** Reverse-transliterate Latin back to a native script (`'el'`, `'ru'`, or `'uk'`). */
 export declare function reverseTransliterate(text: string, options: {
     lang: ReverseLang;
 }): string;
-/** Every character in `text` with no romanization, as `{ char, offset }` (byte offset), in order. */
+/**
+ * Every character in `text` with no romanization, as `{ char, offset }` (byte offset), in
+ * order. An unknown `lang` throws {@link DisarmInvalidArgument}.
+ */
 export declare function findUntranslatable(text: string, options?: TransliterateOptions): Untranslatable[];
 /** Fold cross-script confusables toward `target` (default `'latin'`). */
 export declare function normalizeConfusables(text: string, options?: {
     target?: TargetScript;
     digitPolicy?: DigitPolicy;
 }): string;
+/**
+ * Whether `text` is already its own canonical form under `preset` (#730).
+ *
+ * The verification-path counterpart to the presets: text in, normalized text out is the
+ * generation path, and this is the question a caller asks about bytes that arrive already
+ * bound. `hasAnomalies` is not this predicate — 142,760 assigned code points are reported
+ * clean by the detector and are not their own canonical form.
+ *
+ * `preset` is any name in the preset registry or any profile, defaulting to
+ * `'canonicalize'`. An unknown one throws {@link DisarmInvalidArgument}.
+ */
+export declare function isCanonical(text: string, options?: {
+    preset?: string;
+}): boolean;
 /** Whether `text` contains a character confusable with `target` (default `'latin'`). */
 export declare function isConfusable(text: string, options?: {
     target?: TargetScript;
@@ -130,7 +155,10 @@ export interface SlugifyOptions {
     hexadecimal?: boolean;
     safeChars?: string;
 }
-/** Generate a URL-safe slug. Mirrors the core's `SlugConfig` defaults. */
+/**
+ * Generate a URL-safe slug. Mirrors the core's `SlugConfig` defaults. An unknown `lang`
+ * throws {@link DisarmInvalidArgument}.
+ */
 export declare function slugify(text: string, options?: SlugifyOptions): string;
 /** Strip diacritics (`"café"` → `"cafe"`). */
 export declare function stripAccents(text: string): string;
@@ -169,10 +197,29 @@ export type CollisionKey = 'fold_case' | 'search_key' | 'catalog_key' | 'canonic
 export declare function findKeyCollisions(values: string[], key: CollisionKey, options?: {
     lang?: string;
 }): KeyCollision[];
-/** Replace emoji with their plain names. `stripModifiers` drops skin-tone/variation marks. */
+/**
+ * Replace emoji with their plain names. `stripModifiers` drops skin-tone/variation marks.
+ * An emoji CLDR cannot name — a regional indicator or a Plane 14 tag character standing
+ * alone — becomes `'[?]'`, the sentinel {@link transliterate} writes, and the default in
+ * every binding.
+ */
 export declare function demojize(text: string, options?: {
     stripModifiers?: boolean;
 }): string;
+/** Replace every emoji with `replacement`, verbatim (#972).
+ *
+ * The counterpart to {@link demojize}, and a different question of a different table.
+ * `demojize` asks *what does CLDR call this?*, so its domain is the CLDR name table,
+ * which is wider than the emoji: `demojize('x™y')` is `'x trade mark y'`. This asks *is
+ * this an emoji by the UCD's properties?* — `Emoji_Presentation=Yes`, an `Emoji=Yes`
+ * base carrying `U+FE0F` (not an `Extended_Pictographic` one, so `★` + `U+FE0F` stays),
+ * and the ZWJ, modifier, keycap and flag sequences on those. Nothing
+ * else moves.
+ *
+ * `replacement` is inserted exactly as given, with no padding and no whitespace collapse:
+ * `''` closes an intra-word split (`aa🔥bb` → `aabb`) and `' '` keeps two words apart
+ * (`stop🛑now` → `stop now`), and no rule serves both. */
+export declare function replaceEmoji(text: string, replacement?: string): string;
 /** Apply a Unicode normalization `form` (default `'NFC'`). */
 export declare function normalize(text: string, options?: {
     form?: NormalizationForm;
@@ -206,11 +253,20 @@ export declare function stripVariationSelectors(text: string): string;
 export declare function stripNoncharacters(text: string): string;
 /** Strip every Private Use Area code point (#413). */
 export declare function stripPua(text: string): string;
-/** Cap combining marks per base character at `maxMarks` (default `2`). */
+/**
+ * Cap the marks of each combining class on one base character at `maxMarks`, a
+ * non-negative integer. The default is the core's, 3 — equal to {@link isZalgo}'s
+ * threshold (#788), so this never strips from text `isZalgo` declines to flag. It is read
+ * from the core rather than restated here: this layer had kept the old cap of 2
+ * (`formal/bindings`, B1).
+ */
 export declare function stripZalgo(text: string, options?: {
     maxMarks?: number;
 }): string;
-/** Whether any base character carries more than `threshold` (default `3`) combining marks. */
+/**
+ * Whether any base character carries more than `threshold` marks of one combining class.
+ * The default is the core's, 3.
+ */
 export declare function isZalgo(text: string, options?: {
     threshold?: number;
 }): boolean;
@@ -219,7 +275,9 @@ export declare function isZalgo(text: string, options?: {
  * the half of the pair that lets a caller reject input instead of comparing a value the
  * sender never wrote.
  */
-export declare function canonicalizeStrict(text: string): string;
+export declare function canonicalizeStrict(text: string, options?: {
+    digitPolicy?: DigitPolicy;
+}): string;
 /**
  * Strip the non-interchange and invisible classes while KEEPING the script.
  *
@@ -231,17 +289,22 @@ export declare function canonicalizeStrict(text: string): string;
  */
 export declare function stripFormat(text: string): string;
 /** Remove obfuscation (zero-width, bidi, combining-mark abuse, homoglyphs) while keeping legible content. */
-export declare function stripObfuscation(text: string): string;
+export declare function stripObfuscation(text: string, options?: {
+    digitPolicy?: DigitPolicy;
+}): string;
 /**
- * Canonicalize text for security-sensitive comparison: NFKC → strip bidi/format
- * → strip invisible classes (#413) → strip control → strip zero-width → collapse
- * whitespace → cap combining marks (anti-zalgo) → NFC → confusables → NFC
- * (confusables sandwiched between NFC passes for idempotency).
+ * Canonicalize text for security-sensitive comparison: resolve deletions → NFKC →
+ * strip bidi/format → strip invisible classes (#413) → strip control → strip
+ * zero-width → collapse whitespace → drop repeated marks → cap combining marks
+ * (anti-zalgo) → NFC → confusables and NFC to a fixed point → drop repeated marks
+ * → cap combining marks again (the fold is iterated with NFC for idempotency).
  *
  * The name describes the mechanism (Unicode canonicalization for matching), not
  * a safety guarantee — this is not an output sanitizer; encode at the sink.
  */
-export declare function canonicalize(text: string): string;
+export declare function canonicalize(text: string, options?: {
+    digitPolicy?: DigitPolicy;
+}): string;
 /**
  * @deprecated Renamed to {@link canonicalize} in 0.11 (the `*Clean` name
  * overpromised safety); removed in 1.0.
@@ -264,7 +327,13 @@ export interface SanitizeFilenameOptions {
     lang?: string;
     preserveExtension?: boolean;
 }
-/** Turn arbitrary text into a filesystem-safe filename. */
+/**
+ * Turn arbitrary text into a filesystem-safe filename.
+ *
+ * `separator` must be printable, non-space ASCII with no character illegal on
+ * `platform` and no path separator (`/`, `\`); anything else throws
+ * {@link DisarmInvalidArgument}. `''` is allowed.
+ */
 export declare function sanitizeFilename(text: string, options?: SanitizeFilenameOptions): string;
 /**
  * Case/accent/script-insensitive search lookup key (like {@link catalogKey}
@@ -272,6 +341,7 @@ export declare function sanitizeFilename(text: string, options?: SanitizeFilenam
  */
 export declare function searchKey(text: string, options?: {
     lang?: string;
+    digitPolicy?: DigitPolicy;
 }): string;
 /**
  * Collation sort key — like {@link searchKey} but preserves base accented
@@ -279,6 +349,7 @@ export declare function searchKey(text: string, options?: {
  */
 export declare function sortKey(text: string, options?: {
     lang?: string;
+    digitPolicy?: DigitPolicy;
 }): string;
 /**
  * Library catalog deduplication key — like {@link searchKey} plus confusable
@@ -288,7 +359,38 @@ export declare function sortKey(text: string, options?: {
 export declare function catalogKey(text: string, options?: {
     lang?: string;
     strictIso9?: boolean;
+    digitPolicy?: DigitPolicy;
 }): string;
+/**
+ * The TR39 identifier skeleton plus the two prototype classes disarm's table keeps
+ * apart (#650). A spoof key: its only job is to make confusable identifiers collide,
+ * and its output is never for display. `digitPolicy` `'numeric'` (default) applies the
+ * letter half only; `'tr39'` adds `1 ≡ l` and `0 ≡ O`; `'preserve'` keeps a non-Latin
+ * numeral in its script.
+ */
+export declare function skeletonKey(text: string, options?: {
+    digitPolicy?: DigitPolicy;
+}): string;
+/**
+ * Levenshtein edit distance between `a` and `b`, in characters (#894) — the one class of
+ * registry spoofing the confusable tables deliberately do not model (`paypa1`, `adm1n`).
+ * Canonicalize both sides first when composed and decomposed spellings should compare
+ * equal.
+ */
+export declare function editDistance(a: string, b: string): number;
+/** A candidate and how far {@link nearestMatch} found it from the value asked about. */
+export interface NearestMatch {
+    value: string;
+    distance: number;
+}
+/**
+ * The candidate closest to `value`, with its distance, or `null` beyond `maxDistance`
+ * (default 1). Reports; it does not decide. An exact match is reported with distance 0,
+ * and ties go to the first candidate at the lowest distance (#894).
+ */
+export declare function nearestMatch(value: string, candidates: string[], options?: {
+    maxDistance?: number;
+}): NearestMatch | null;
 /** Options for {@link mlNormalize}. */
 export interface MlNormalizeOptions {
     /** Language code selecting the transliteration table; omit for none. */
@@ -305,8 +407,9 @@ export interface MlNormalizeOptions {
     foldCase?: boolean;
 }
 /**
- * ML/NLP normalization: NFKC → emoji→text → transliterate → strip accents →
- * [case fold] → strip control → strip zero-width → collapse whitespace.
+ * ML/NLP normalization: resolve deletions → NFKC → emoji→text → transliterate →
+ * strip accents → emoji→text → [case fold] → strip control → strip zero-width →
+ * collapse whitespace → NFC.
  *
  * Note this folds no confusables — it is not a homoglyph defence at any setting. Put
  * {@link normalizeConfusables} in front of it when a model needs both.
@@ -370,6 +473,21 @@ export declare function langInfo(code: string): LangMeta;
  * unknown name throws {@link DisarmInvalidArgument}.
  */
 export declare function scriptInfo(name: string): ScriptMeta;
+/** TR39 sources whose prototype is in `script`, and how many of those disarm's bundled
+ * tables fold (#963).
+ *
+ * The denominator {@link unmappedConfusables} does not have. That function measures one
+ * bundled table against the whole 6,565-source population, which is the right question
+ * for a target disarm ships and a misleading one for a script it does not: Greek reports
+ * almost the entire population unmapped, and the number means only "there is no Greek
+ * table".
+ *
+ * `folded` counts sources any bundled table reaches, not sources folded *toward* this
+ * script — Greek is 71 of 159 because the Latin table folds Greek letters that look
+ * Latin. The grouping uses the UCD's script property, so `"Yi"` and 18 other scripts
+ * disarm's own enum does not name are addressable here. A script disarm knows that TR39
+ * never uses as a prototype returns 0 of 0. */
+export declare function confusableCoverage(script: string): ConfusableCoverage;
 /**
  * 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,