disarm 0.0.0 → 0.11.0

package/index.d.ts

@@ -0,0 +1,261 @@
+import { Lexicon, Pipeline } from './binding';
+import type { Untranslatable, AutoLangInspection, LangMeta, ScriptMeta, Finding as NativeFinding, AnomalyReport as NativeAnomalyReport } from './binding';
+export type { Untranslatable, AutoLangInspection, LangMeta, ScriptMeta };
+/**
+ * A reusable, opaque lexicon handle (HAI-SDLC 6.1). `hasAnomalies` /
+ * `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.
+ */
+export { Lexicon };
+/**
+ * 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
+ * inputs via `.process(text)` — the profile's steps are validated and compiled
+ * a single time and reused across calls, rather than re-resolved each call.
+ *
+ * ```ts
+ * const pipe = getPipeline('search_index') // build once
+ * pipe.process('Café')   // → 'cafe'
+ * pipe.process('Москва') // → 'moskva'   (same handle, many inputs)
+ * ```
+ */
+export { Pipeline };
+/** The anomaly branch that fired for a finding. */
+export type AnomalyKind = 'invisible' | 'bidi' | 'zalgo' | 'mixed_script' | 'leet' | 'segmentation';
+/**
+ * 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`.
+ */
+export type Finding = Omit<NativeFinding, 'kind'> & {
+    kind: AnomalyKind;
+};
+/** Structured anomaly report, with {@link Finding}s carrying a typed `kind`. */
+export type AnomalyReport = Omit<NativeAnomalyReport, 'findings'> & {
+    findings: Finding[];
+};
+/** Base class for every error disarm raises, so callers can `catch (e) { if (e instanceof DisarmError) … }`. */
+export declare class DisarmError extends Error {
+    constructor(message: string);
+}
+/** An invalid argument — an unknown scheme/target/form/platform token, etc. */
+export declare class DisarmInvalidArgument extends DisarmError {
+    constructor(message: string);
+}
+/** 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';
+/** Unicode normalization form. */
+export type NormalizationForm = 'NFC' | 'NFD' | 'NFKC' | 'NFKD';
+/** Filename-safety platform ruleset. */
+export type Platform = 'universal' | 'windows' | 'posix';
+/** Reverse-transliteration target language. */
+export type ReverseLang = 'el' | 'ru' | 'uk';
+export interface TransliterateOptions {
+    /** The scheme (default: `'default'`). */
+    scheme?: Scheme;
+    /** A language profile applied on top of the scheme (e.g. `'uk'`, `'de'`, or `'auto'`). */
+    lang?: string;
+}
+/** Romanize Unicode text to ASCII. */
+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. */
+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;
+}): string;
+/** Whether `text` contains a character confusable with `target` (default `'latin'`). */
+export declare function isConfusable(text: string, options?: {
+    target?: TargetScript;
+}): boolean;
+export interface SlugifyOptions {
+    separator?: string;
+    lowercase?: boolean;
+    maxLength?: number;
+    wordBoundary?: boolean;
+    saveOrder?: boolean;
+    stopwords?: string[];
+    allowUnicode?: boolean;
+    lang?: string;
+    entities?: boolean;
+    decimal?: boolean;
+    hexadecimal?: boolean;
+    safeChars?: string;
+}
+/** Generate a URL-safe slug. Mirrors the core's `SlugConfig` defaults. */
+export declare function slugify(text: string, options?: SlugifyOptions): string;
+/** Strip diacritics (`"café"` → `"cafe"`). */
+export declare function stripAccents(text: string): string;
+/** Full Unicode case fold — more aggressive than `String.toLowerCase()`. */
+export declare function foldCase(text: string): string;
+/** Replace emoji with their plain names. `stripModifiers` drops skin-tone/variation marks. */
+export declare function demojize(text: string, options?: {
+    stripModifiers?: boolean;
+}): string;
+/** Apply a Unicode normalization `form` (default `'NFC'`). */
+export declare function normalize(text: string, options?: {
+    form?: NormalizationForm;
+}): string;
+/** Whether `text` is already in normalization `form` (default `'NFC'`). */
+export declare function isNormalized(text: string, options?: {
+    form?: NormalizationForm;
+}): boolean;
+/**
+ * Fold Unicode whitespace runs to single ASCII spaces and trim the ends (#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 `stripControlChars` /
+ * `stripZeroWidthChars` for that. Folding the line controls (rather than
+ * deleting them) means `a\rb` → `a b`, never `ab`.
+ */
+export declare function collapseWhitespace(text: string): string;
+/** Remove C0/C1 control characters (except tab/newline). */
+export declare function stripControlChars(text: string): string;
+/** Remove zero-width characters (ZWSP/ZWNJ/ZWJ/word-joiner). */
+export declare function stripZeroWidthChars(text: string): string;
+/** Remove Unicode bidirectional control characters. */
+export declare function stripBidi(text: string): string;
+/** Strip the Unicode Tags block (U+E0000–U+E007F), preserving valid emoji flag sequences (#413). */
+export declare function stripTags(text: string): string;
+/** Strip every variation selector (VS1–VS256) (#413). */
+export declare function stripVariationSelectors(text: string): string;
+/** Strip every Unicode noncharacter (#413). */
+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`). */
+export declare function stripZalgo(text: string, options?: {
+    maxMarks?: number;
+}): string;
+/** Whether any base character carries more than `threshold` (default `3`) combining marks. */
+export declare function isZalgo(text: string, options?: {
+    threshold?: number;
+}): boolean;
+/** Remove obfuscation (zero-width, bidi, combining-mark abuse, homoglyphs) while keeping legible content. */
+export declare function stripObfuscation(text: string): 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).
+ *
+ * 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;
+/**
+ * @deprecated Renamed to {@link canonicalize} in 0.11 (the `*Clean` name
+ * overpromised safety); removed in 1.0.
+ */
+export declare function securityClean(text: string): string;
+/**
+ * Build a reusable {@link Pipeline} handle for a named policy profile (#404).
+ * Resolve and compile the profile's steps once here, then call `.process(text)`
+ * on the returned handle for each input — the per-call cost is just running the
+ * already-compiled steps, not re-resolving the profile (mirrors {@link Lexicon}).
+ *
+ * An unknown `profile` throws {@link DisarmInvalidArgument} (naming the
+ * available profiles).
+ */
+export declare function getPipeline(profile: string): Pipeline;
+export interface SanitizeFilenameOptions {
+    separator?: string;
+    maxLength?: number;
+    platform?: Platform;
+    lang?: string;
+    preserveExtension?: boolean;
+}
+/** Turn arbitrary text into a filesystem-safe filename. */
+export declare function sanitizeFilename(text: string, options?: SanitizeFilenameOptions): string;
+/**
+ * Case/accent/script-insensitive search lookup key (like {@link catalogKey}
+ * without confusable folding). `lang` selects the transliteration table.
+ */
+export declare function searchKey(text: string, options?: {
+    lang?: string;
+}): string;
+/**
+ * Collation sort key — like {@link searchKey} but preserves base accented
+ * characters for correct ordering. `lang` selects the transliteration table.
+ */
+export declare function sortKey(text: string, options?: {
+    lang?: string;
+}): string;
+/**
+ * Library catalog deduplication key — like {@link searchKey} plus confusable
+ * folding. `lang` selects the transliteration table; `strictIso9` (default
+ * `false`) picks the ISO 9:1995 Cyrillic scheme.
+ */
+export declare function catalogKey(text: string, options?: {
+    lang?: string;
+    strictIso9?: boolean;
+}): string;
+/** Number of grapheme clusters (user-perceived characters). */
+export declare function graphemeLen(text: string): number;
+/** Split `text` into grapheme-cluster strings. */
+export declare function graphemeSplit(text: string): string[];
+/** Truncate to at most `maxGraphemes` clusters, never cutting through one. */
+export declare function graphemeTruncate(text: string, maxGraphemes: number): string;
+/** Display width (terminal columns) of a single grapheme `cluster` by East Asian Width. */
+export declare function graphemeWidth(cluster: string, options?: {
+    ambiguousWide?: boolean;
+}): number;
+/** Total display width (terminal columns) of `text`. */
+export declare function terminalWidth(text: string, options?: {
+    ambiguousWide?: boolean;
+}): number;
+/** Whether the hostname looks like a mixed-script / confusable IDN spoof (a `false` is not a safety guarantee). */
+export declare function isSuspiciousHostname(host: string): boolean;
+/** The Unicode scripts present, in first-appearance order (Common/Inherited excluded). */
+export declare function detectScripts(text: string): string[];
+/** Whether `text` mixes characters from more than one script. */
+export declare function isMixedScript(text: string): boolean;
+/**
+ * Whether `text` mixes strong left-to-right and strong right-to-left characters
+ * — the precondition for Bidi display-reordering ("BiDi Swap", #412). Fires on
+ * the real letters (no `U+202x` override); a `false` result is not a safety
+ * guarantee.
+ */
+export declare function hasBidiConflict(text: string): boolean;
+/** Explain how `lang: 'auto'` detection resolves `text`. */
+export declare function inspectAutoLang(text: string): AutoLangInspection;
+/**
+ * Static facts about a language `code` — its English name, primary script,
+ * region, and context-awareness. An unknown code throws
+ * {@link DisarmInvalidArgument}.
+ */
+export declare function langInfo(code: string): LangMeta;
+/**
+ * Static facts about a script by `name` — its default language code (if any),
+ * an example string, and whether its transliteration is context-aware. An
+ * unknown name throws {@link DisarmInvalidArgument}.
+ */
+export declare function scriptInfo(name: string): ScriptMeta;
+/** Every Unicode script name known to the transliteration tables. */
+export declare function listScripts(): string[];
+/** Every language code that has a context-aware transliteration profile. */
+export declare function listContextLangs(): string[];
+/**
+ * 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 (a `Set` or
+ * array) — or a prebuilt {@link Lexicon} handle, which avoids rebuilding the
+ * internal set on every call — used only by the leet and segmentation branches.
+ */
+export declare function hasAnomalies(text: string, lexicon?: Iterable<string> | Lexicon): boolean;
+/**
+ * Full anomaly analysis: an `AnomalyReport` 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).
+ * `lexicon` may be a `Set`/array of words or a prebuilt {@link Lexicon} handle.
+ */
+export declare function inspectAnomalies(text: string, lexicon?: Iterable<string> | Lexicon): AnomalyReport;

package/index.js

@@ -0,0 +1,413 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DisarmInvalidArgument = exports.DisarmError = exports.Pipeline = exports.Lexicon = void 0;
+exports.transliterate = transliterate;
+exports.reverseTransliterate = reverseTransliterate;
+exports.findUntranslatable = findUntranslatable;
+exports.normalizeConfusables = normalizeConfusables;
+exports.isConfusable = isConfusable;
+exports.slugify = slugify;
+exports.stripAccents = stripAccents;
+exports.foldCase = foldCase;
+exports.demojize = demojize;
+exports.normalize = normalize;
+exports.isNormalized = isNormalized;
+exports.collapseWhitespace = collapseWhitespace;
+exports.stripControlChars = stripControlChars;
+exports.stripZeroWidthChars = stripZeroWidthChars;
+exports.stripBidi = stripBidi;
+exports.stripTags = stripTags;
+exports.stripVariationSelectors = stripVariationSelectors;
+exports.stripNoncharacters = stripNoncharacters;
+exports.stripPua = stripPua;
+exports.stripZalgo = stripZalgo;
+exports.isZalgo = isZalgo;
+exports.stripObfuscation = stripObfuscation;
+exports.canonicalize = canonicalize;
+exports.securityClean = securityClean;
+exports.getPipeline = getPipeline;
+exports.sanitizeFilename = sanitizeFilename;
+exports.searchKey = searchKey;
+exports.sortKey = sortKey;
+exports.catalogKey = catalogKey;
+exports.graphemeLen = graphemeLen;
+exports.graphemeSplit = graphemeSplit;
+exports.graphemeTruncate = graphemeTruncate;
+exports.graphemeWidth = graphemeWidth;
+exports.terminalWidth = terminalWidth;
+exports.isSuspiciousHostname = isSuspiciousHostname;
+exports.detectScripts = detectScripts;
+exports.isMixedScript = isMixedScript;
+exports.hasBidiConflict = hasBidiConflict;
+exports.inspectAutoLang = inspectAutoLang;
+exports.langInfo = langInfo;
+exports.scriptInfo = scriptInfo;
+exports.listScripts = listScripts;
+exports.listContextLangs = listContextLangs;
+exports.hasAnomalies = hasAnomalies;
+exports.inspectAnomalies = inspectAnomalies;
+/**
+ * disarm for Node.js — Unicode confusable/text-security building blocks, powered
+ * by a pure-Rust core (#44).
+ *
+ * This is the idiomatic TypeScript layer over the raw napi binding (`./binding`):
+ * it adds options objects with sensible defaults, string-union token types, and a
+ * native {@link DisarmError} class. The behaviour is defined once in the Rust core
+ * and inherited here — see https://docs.disarm.dev for the language-neutral guides.
+ */
+const native = __importStar(require("./binding"));
+const binding_1 = require("./binding");
+Object.defineProperty(exports, "Lexicon", { enumerable: true, get: function () { return binding_1.Lexicon; } });
+Object.defineProperty(exports, "Pipeline", { enumerable: true, get: function () { return binding_1.Pipeline; } });
+// ── Errors ──────────────────────────────────────────────────────────────────
+/** Base class for every error disarm raises, so callers can `catch (e) { if (e instanceof DisarmError) … }`. */
+class DisarmError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DisarmError';
+    }
+}
+exports.DisarmError = DisarmError;
+/** An invalid argument — an unknown scheme/target/form/platform token, etc. */
+class DisarmInvalidArgument extends DisarmError {
+    constructor(message) {
+        super(message);
+        this.name = 'DisarmInvalidArgument';
+    }
+}
+exports.DisarmInvalidArgument = DisarmInvalidArgument;
+const INVALID_ARG_TAG = 'DisarmInvalidArgument: ';
+const ERROR_TAG = 'DisarmError: ';
+/**
+ * Run a native call, re-raising its tagged napi error as the matching
+ * `DisarmError` subclass. The native shim prefixes fallible messages with
+ * `"DisarmInvalidArgument: "` or `"DisarmError: "`; we strip the matched tag
+ * cleanly. Any other throw — an untagged `Error`, or a non-`Error` value — is
+ * still wrapped as a `DisarmError` so nothing leaks out unwrapped.
+ */
+function call(fn) {
+    try {
+        return fn();
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (msg.startsWith(INVALID_ARG_TAG)) {
+            throw new DisarmInvalidArgument(msg.slice(INVALID_ARG_TAG.length));
+        }
+        if (msg.startsWith(ERROR_TAG)) {
+            throw new DisarmError(msg.slice(ERROR_TAG.length));
+        }
+        throw new DisarmError(msg);
+    }
+}
+/** Romanize Unicode text to ASCII. */
+function transliterate(text, options = {}) {
+    const { scheme = 'default', lang } = options;
+    if (scheme === 'default' && lang == null) {
+        return native.transliterate(text);
+    }
+    return call(() => native.transliterateOpts(text, scheme, lang ?? undefined));
+}
+/** Reverse-transliterate Latin back to a native script (`'el'`, `'ru'`, or `'uk'`). */
+function reverseTransliterate(text, options) {
+    return call(() => native.reverseTransliterate(text, options.lang));
+}
+/** Every character in `text` with no romanization, as `{ char, offset }` (byte offset), in order. */
+function findUntranslatable(text, options = {}) {
+    const { scheme = 'default', lang } = options;
+    return call(() => native.findUntranslatable(text, scheme, lang ?? undefined));
+}
+// ── Confusables (TR39) ──────────────────────────────────────────────────────
+/** Fold cross-script confusables toward `target` (default `'latin'`). */
+function normalizeConfusables(text, options = {}) {
+    return call(() => native.normalizeConfusables(text, options.target ?? 'latin'));
+}
+/** Whether `text` contains a character confusable with `target` (default `'latin'`). */
+function isConfusable(text, options = {}) {
+    return call(() => native.isConfusable(text, options.target ?? 'latin'));
+}
+/** Generate a URL-safe slug. Mirrors the core's `SlugConfig` defaults. */
+function slugify(text, options = {}) {
+    return call(() => native.slugify(text, {
+        separator: options.separator ?? '-',
+        lowercase: options.lowercase ?? true,
+        maxLength: options.maxLength ?? 0,
+        wordBoundary: options.wordBoundary ?? false,
+        saveOrder: options.saveOrder ?? false,
+        stopwords: options.stopwords ?? [],
+        allowUnicode: options.allowUnicode ?? false,
+        lang: options.lang,
+        entities: options.entities ?? true,
+        decimal: options.decimal ?? true,
+        hexadecimal: options.hexadecimal ?? true,
+        safeChars: options.safeChars ?? '',
+    }));
+}
+// ── Canonicalization primitives ─────────────────────────────────────────────
+/** Strip diacritics (`"café"` → `"cafe"`). */
+function stripAccents(text) {
+    return native.stripAccents(text);
+}
+/** Full Unicode case fold — more aggressive than `String.toLowerCase()`. */
+function foldCase(text) {
+    return native.foldCase(text);
+}
+/** Replace emoji with their plain names. `stripModifiers` drops skin-tone/variation marks. */
+function demojize(text, options = {}) {
+    return native.demojize(text, options.stripModifiers ?? false);
+}
+// ── Normalization ───────────────────────────────────────────────────────────
+/** Apply a Unicode normalization `form` (default `'NFC'`). */
+function normalize(text, options = {}) {
+    return call(() => native.normalize(text, options.form ?? 'NFC'));
+}
+/** Whether `text` is already in normalization `form` (default `'NFC'`). */
+function isNormalized(text, options = {}) {
+    return call(() => native.isNormalized(text, options.form ?? 'NFC'));
+}
+// ── Text cleaning ───────────────────────────────────────────────────────────
+/**
+ * Fold Unicode whitespace runs to single ASCII spaces and trim the ends (#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 `stripControlChars` /
+ * `stripZeroWidthChars` for that. Folding the line controls (rather than
+ * deleting them) means `a\rb` → `a b`, never `ab`.
+ */
+function collapseWhitespace(text) {
+    return native.collapseWhitespace(text);
+}
+/** Remove C0/C1 control characters (except tab/newline). */
+function stripControlChars(text) {
+    return native.stripControlChars(text);
+}
+/** Remove zero-width characters (ZWSP/ZWNJ/ZWJ/word-joiner). */
+function stripZeroWidthChars(text) {
+    return native.stripZeroWidthChars(text);
+}
+/** Remove Unicode bidirectional control characters. */
+function stripBidi(text) {
+    return native.stripBidi(text);
+}
+/** Strip the Unicode Tags block (U+E0000–U+E007F), preserving valid emoji flag sequences (#413). */
+function stripTags(text) {
+    return native.stripTags(text);
+}
+/** Strip every variation selector (VS1–VS256) (#413). */
+function stripVariationSelectors(text) {
+    return native.stripVariationSelectors(text);
+}
+/** Strip every Unicode noncharacter (#413). */
+function stripNoncharacters(text) {
+    return native.stripNoncharacters(text);
+}
+/** Strip every Private Use Area code point (#413). */
+function stripPua(text) {
+    return native.stripPua(text);
+}
+/** Cap combining marks per base character at `maxMarks` (default `2`). */
+function stripZalgo(text, options = {}) {
+    return call(() => native.stripZalgo(text, options.maxMarks ?? 2));
+}
+/** Whether any base character carries more than `threshold` (default `3`) combining marks. */
+function isZalgo(text, options = {}) {
+    return call(() => native.isZalgo(text, options.threshold ?? 3));
+}
+// ── Deobfuscation & security presets ────────────────────────────────────────
+/** Remove obfuscation (zero-width, bidi, combining-mark abuse, homoglyphs) while keeping legible content. */
+function stripObfuscation(text) {
+    return call(() => native.stripObfuscation(text));
+}
+/**
+ * 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).
+ *
+ * The name describes the mechanism (Unicode canonicalization for matching), not
+ * a safety guarantee — this is not an output sanitizer; encode at the sink.
+ */
+function canonicalize(text) {
+    return call(() => native.canonicalize(text));
+}
+/**
+ * @deprecated Renamed to {@link canonicalize} in 0.11 (the `*Clean` name
+ * overpromised safety); removed in 1.0.
+ */
+function securityClean(text) {
+    return canonicalize(text);
+}
+/**
+ * Build a reusable {@link Pipeline} handle for a named policy profile (#404).
+ * Resolve and compile the profile's steps once here, then call `.process(text)`
+ * on the returned handle for each input — the per-call cost is just running the
+ * already-compiled steps, not re-resolving the profile (mirrors {@link Lexicon}).
+ *
+ * An unknown `profile` throws {@link DisarmInvalidArgument} (naming the
+ * available profiles).
+ */
+function getPipeline(profile) {
+    return call(() => native.getPipeline(profile));
+}
+/** Turn arbitrary text into a filesystem-safe filename. */
+function sanitizeFilename(text, options = {}) {
+    return call(() => native.sanitizeFilename(text, options.separator ?? '_', options.maxLength ?? 255, options.platform ?? 'universal', options.lang ?? undefined, options.preserveExtension ?? true));
+}
+// ── Key-derivation presets ──────────────────────────────────────────────────
+/**
+ * Case/accent/script-insensitive search lookup key (like {@link catalogKey}
+ * without confusable folding). `lang` selects the transliteration table.
+ */
+function searchKey(text, options = {}) {
+    return call(() => native.searchKey(text, options.lang ?? undefined));
+}
+/**
+ * Collation sort key — like {@link searchKey} but preserves base accented
+ * characters for correct ordering. `lang` selects the transliteration table.
+ */
+function sortKey(text, options = {}) {
+    return call(() => native.sortKey(text, options.lang ?? undefined));
+}
+/**
+ * Library catalog deduplication key — like {@link searchKey} plus confusable
+ * folding. `lang` selects the transliteration table; `strictIso9` (default
+ * `false`) picks the ISO 9:1995 Cyrillic scheme.
+ */
+function catalogKey(text, options = {}) {
+    return call(() => native.catalogKey(text, options.lang ?? undefined, options.strictIso9 ?? false));
+}
+// ── Grapheme clusters ───────────────────────────────────────────────────────
+/** Number of grapheme clusters (user-perceived characters). */
+function graphemeLen(text) {
+    return native.graphemeLen(text);
+}
+/** Split `text` into grapheme-cluster strings. */
+function graphemeSplit(text) {
+    return native.graphemeSplit(text);
+}
+/** Truncate to at most `maxGraphemes` clusters, never cutting through one. */
+function graphemeTruncate(text, maxGraphemes) {
+    return call(() => native.graphemeTruncate(text, maxGraphemes));
+}
+/** Display width (terminal columns) of a single grapheme `cluster` by East Asian Width. */
+function graphemeWidth(cluster, options = {}) {
+    return native.graphemeWidth(cluster, options.ambiguousWide ?? false);
+}
+/** Total display width (terminal columns) of `text`. */
+function terminalWidth(text, options = {}) {
+    return native.terminalWidth(text, options.ambiguousWide ?? false);
+}
+// ── Hostname / script analysis ──────────────────────────────────────────────
+/** Whether the hostname looks like a mixed-script / confusable IDN spoof (a `false` is not a safety guarantee). */
+function isSuspiciousHostname(host) {
+    return native.isSuspiciousHostname(host);
+}
+/** The Unicode scripts present, in first-appearance order (Common/Inherited excluded). */
+function detectScripts(text) {
+    return native.detectScripts(text);
+}
+/** Whether `text` mixes characters from more than one script. */
+function isMixedScript(text) {
+    return native.isMixedScript(text);
+}
+/**
+ * Whether `text` mixes strong left-to-right and strong right-to-left characters
+ * — the precondition for Bidi display-reordering ("BiDi Swap", #412). Fires on
+ * the real letters (no `U+202x` override); a `false` result is not a safety
+ * guarantee.
+ */
+function hasBidiConflict(text) {
+    return native.hasBidiConflict(text);
+}
+/** Explain how `lang: 'auto'` detection resolves `text`. */
+function inspectAutoLang(text) {
+    return native.inspectAutoLang(text);
+}
+// ── Metadata introspection (#404) ───────────────────────────────────────────
+/**
+ * Static facts about a language `code` — its English name, primary script,
+ * region, and context-awareness. An unknown code throws
+ * {@link DisarmInvalidArgument}.
+ */
+function langInfo(code) {
+    return call(() => native.langInfo(code));
+}
+/**
+ * Static facts about a script by `name` — its default language code (if any),
+ * an example string, and whether its transliteration is context-aware. An
+ * unknown name throws {@link DisarmInvalidArgument}.
+ */
+function scriptInfo(name) {
+    return call(() => native.scriptInfo(name));
+}
+/** Every Unicode script name known to the transliteration tables. */
+function listScripts() {
+    return native.listScripts();
+}
+/** Every language code that has a context-aware transliteration profile. */
+function listContextLangs() {
+    return native.listContextLangs();
+}
+// ── Anomaly detection ───────────────────────────────────────────────────────
+/**
+ * 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 (a `Set` or
+ * array) — or a prebuilt {@link Lexicon} handle, which avoids rebuilding the
+ * internal set on every call — used only by the leet and segmentation branches.
+ */
+function hasAnomalies(text, lexicon = []) {
+    if (lexicon instanceof binding_1.Lexicon) {
+        return native.hasAnomalies(text, lexicon);
+    }
+    return native.hasAnomalies(text, Array.isArray(lexicon) ? lexicon : [...lexicon]);
+}
+/**
+ * Full anomaly analysis: an `AnomalyReport` 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).
+ * `lexicon` may be a `Set`/array of words or a prebuilt {@link Lexicon} handle.
+ */
+function inspectAnomalies(text, lexicon = []) {
+    if (lexicon instanceof binding_1.Lexicon) {
+        return native.inspectAnomalies(text, lexicon);
+    }
+    const words = Array.isArray(lexicon) ? lexicon : [...lexicon];
+    return native.inspectAnomalies(text, words);
+}