Ambiggy

Ambiggy is a Rust library for detecting ambiguous characters (homoglyphs) in text strings. It is particularly useful for identifying potential security risks or confusion in file paths, URLs, and code.

Features

• Homoglyph Detection: Identifies characters that look similar to others (e.g., Greek Alpha 'Α' vs Latin 'A').
• Position Tracking: Returns the exact position of each ambiguous character.
• Configurable: Can be enabled or disabled via settings in integrated environments.
• Blitz Integration: Integrated into the Blitz editor's core path parsing logic.

Architecture

graph TD
    A[Input Text] --> B[check function]
    B --> C{Ambiguous Table}
    C --> D[Unicode Confusable Map]
    D --> E[AmbiguousChar Vec]
    E --> F[UI Warning / Log]

Usage in Blitz

In the Blitz editor, Ambiggy is used to scan path strings and warn the user if they contain characters that could be misleading.

sequenceDiagram
    participant User
    participant Editor
    participant Ambiggy
    participant Settings

    User->>Editor: Enter Path
    Editor->>Settings: Check if Ambiggy enabled
    Settings-->>Editor: Enabled
    Editor->>Ambiggy: check(path_string)
    Ambiggy-->>Editor: Vec<AmbiguousChar>
    Editor->>User: Show Warning UI (AmbiggyWarning)

Integration Details

• Service Location: services/ambiggy
• Blitz Integration: vendor/blitz/crates/util/src/paths.rs
• UI Component: vendor/blitz/crates/ui/src/components/ambiggy.rs
• Configuration: editor.ambiggy_enabled in Blitz settings.

Performance

Ambiggy is designed to be lightweight and fast. It uses a static lookup table generated during build time, ensuring minimal overhead even for large strings.

Testing

Native Tests

Unit tests are inline in src/lib.rs. Integration tests live in tests/integration.rs.

# Run all native tests (unit + integration)
cargo test

WASM Tests

WASM-specific tests verify the wasm-bindgen bindings and serialization format.

Rust-side WASM tests (tests/wasm.rs):

# Run with wasm-pack (requires wasm32-unknown-unknown target)
wasm-pack test --node --release

JavaScript-side tests (wasm-test/):

cd wasm-test
node test/wasm.test.js

JS tests verify:

• Uint8Array serialization format (12 bytes per result)
• Round-trip decoding of original/confusable/position
• Edge cases (surrogate pairs, null bytes, long strings)
• Memory safety across repeated calls

Test Summary

Suite	Location	Count	Runner
Unit	src/lib.rs	4	cargo test
Integration	tests/integration.rs	5	cargo test
WASM Rust	tests/wasm.rs	8	wasm-pack test --node
WASM JS	wasm-test/test/	22	node

Building WASM

wasm-pack build --target web

Output lands in pkg/ with JS bindings, TypeScript defs, and the .wasm binary.