### Open FuzzySearch Example Project

Source: https://github.com/ordo-one/fuzzymatch/blob/main/README.md

Command to open the interactive search example application.

```bash
open Examples/FuzzySearch/FuzzySearch.xcodeproj
```

--------------------------------

### Install Comparison Suite Prerequisites

Source: https://github.com/ordo-one/fuzzymatch/blob/main/CLAUDE.md

Commands to install necessary dependencies for running benchmark and quality comparison scripts.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

```bash
brew install rapidfuzz-cpp
```

```bash
brew install fzf
```

--------------------------------

### Simple Prefix Match Example

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/SMITH_WATERMAN.md

Illustrates a simple prefix match scenario. It details the steps of bitmask prefiltering, lowercasing with bonus application, Smith-Waterman dynamic programming, and score normalization. The example shows that an exact match check can precede alignment scoring if lengths differ.

```text
Query:     "get"  (queryLen = 3)
Candidate: "getUserById"
Config:    default SmithWatermanConfig

Step 1 — Bitmask prefilter:
  queryMask has bits for g, e, t
  candidateMask has bits for g, e, t, u, s, r, b, y, i, d
  Missing = 0 → passes

Step 2 — Lowercase + bonus:
  Lowercased: "getuserbyid"
  Bonus:      [10, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
               g   e   t  U→u s   e   r  B→b y  I→i d
  (position 0 gets whitespace bonus 10; camelCase at 3,7,9)
  Bonus:      [10, 0, 0, 5, 0, 0, 0, 5, 0, 5, 0]
               g   e   t  U   s   e   r  B   y  I   d

Step 3 — SW DP (showing match row for last query char 't'):
  i=0 (g): M[0] = 16 + 10*2 = 36    (first char, whitespace bonus)
  i=1 (e): M[1] = 36 + 16 + max(10, 4, 0) = 62  (consecutive, carried bonus = 10)
  i=2 (t): M[2] = 62 + 16 + max(10, 4, 0) = 88  (consecutive, carried bonus = 10)
  → rawScore = 88

Step 4 — Normalize:
  maxScore = 3 × 16 + 10 × (2 + 2) = 48 + 40 = 88
  normalizedScore = 88 / 88 = 1.0

  But wait — exact match check would fire first since
  "get" != "getuserbyid" (different lengths), so no exact match.
  Result: ScoredMatch(score: 1.0, kind: .alignment)
```

--------------------------------

### Multi-Word Query Example

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/SMITH_WATERMAN.md

Shows how multi-word queries are handled by splitting them into atoms. This example demonstrates matching 'johnson johnson' against 'Johnson & Johnson' with `splitSpaces = true`, highlighting boundary matches and the summation of scores for each atom.

```text
Query:     "johnson johnson"
Candidate: "Johnson & Johnson"
Config:    default (splitSpaces = true)

Atoms: ["johnson", "johnson"]

Atom 1 ("johnson"):
  Aligns to "Johnson" at start → strong boundary match
  rawScore₁ = high (boundary + consecutive)

Atom 2 ("johnson"):
  Aligns to "Johnson" at end → boundary match after space
  rawScore₂ = high

totalRawScore = rawScore₁ + rawScore₂
maxScore = 2 × (7 × 16 + 10 × (2 + 6)) = 2 × (112 + 80) = 384
normalizedScore = totalRawScore / 384

Both atoms found → match returned as .alignment
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/ordo-one/fuzzymatch/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification.

```text
feat: add support for Unicode normalization
fix: correct boundary detection for digits after underscore
perf: vectorize bitmask prefilter
docs: update algorithm documentation for acronym matching
test: add edge cases for empty candidate strings
```

--------------------------------

### Build fuzzygrep

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Examples/README.md

Compiles the fuzzygrep example tool using the Swift package manager in release mode.

```bash
swift build --package-path Examples -c release
```

--------------------------------

### Consecutive Bonus Propagation Example

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/SMITH_WATERMAN.md

An example demonstrating how boundary bonuses propagate through consecutive character matches.

```text
Query: "bar"
Candidate: "foo_bar"
Bonus array: [10, 0, 0, 0, 8, 0, 0]
              f   o   o   _  b   a   r

Alignment at positions 4, 5, 6:
  'b' at position 4 (boundary bonus = 8):
    M = 16 + 8*2 = 32  (first char multiplied)
    B = 8

  'a' at position 5 (posBonus = 0):
    carriedBonus = max(8, 4) = 8
    effectiveBonus = max(8, 0) = 8
    M = 32 + 16 + 8 = 56
    B = 8 (carried forward)

  'r' at position 6 (posBonus = 0):
    carriedBonus = max(8, 4) = 8
    effectiveBonus = max(8, 0) = 8
    M = 56 + 16 + 8 = 80
    B = 8 (carried forward)
```

--------------------------------

### Install FuzzyMatch via Swift Package Manager

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Sources/FuzzyMatch/FuzzyMatch.docc/GettingStarted.md

Add the dependency to your Package.swift file.

```swift
dependencies: [
    .package(url: "https://github.com/ordo-one/FuzzyMatch.git", from: "1.0.0")
]
```

--------------------------------

### Acronym Matching Example

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/SMITH_WATERMAN.md

Demonstrates the acronym matching process with a specific query and candidate string, showing the boundary mask, word initials, subsequence check, and final score calculation.

```text
Query: "bms"
Candidate: "Bristol-Myers Squibb"

Boundary mask: bits at 0, 8, 14 → word initials: [b, m, s]
Subsequence check: b→b, m→m, s→s ✓
Coverage: 3/3 = 1.0
Score: 0.55 + 0.4 × 1.0 = 0.95 → kind = .acronym
```

--------------------------------

### Typo-Tolerant Highlighting Examples

Source: https://github.com/ordo-one/fuzzymatch/blob/main/README.md

Demonstrates how `highlight()` handles typos, missing characters, doubled characters, and transposed characters by showing which candidate characters participated in the alignment.

```swift
let matcher = FuzzyMatcher()

// Typo: 'a' instead of 'e' — highlights "getUser" (substituted 'e' included)
matcher.highlight("getUserById", against: "getusar")   // → ["getUser"]

// Missing character — highlights around the gap
matcher.highlight("format:modern", against: "modrn")   // → ["mod", "rn"]

// Doubled character — extra char absorbed, highlights normally
matcher.highlight("getUserById", against: "geetuser")  // → ["getUser"]

// Transposed characters — both positions highlighted
matcher.highlight("getUserById", against: "gteuser")   // → ["getUser"]
```

--------------------------------

### Scattered Match with Gap Example

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/SMITH_WATERMAN.md

Demonstrates matching a query with scattered characters across a candidate string that includes gaps. It details the bonus application and the dynamic programming trace, showing how gap penalties affect the score. The normalization step calculates the final score relative to the maximum possible score.

```text
Query:     "ac"  (queryLen = 2)
Candidate: "axxxxc"
Config:    default

Bonus: [10, 0, 0, 0, 0, 0]  (position 0 = whitespace bonus)

DP trace:
  i=0 (a): M[0] = 16 + 10*2 = 36  (first char)
  i=1 (x): G[0] = 36 - 3 = 33     (gap start)
  i=2 (x): G[0] = 33 - 1 = 32     (gap extend)
  i=3 (x): G[0] = 32 - 1 = 31
  i=4 (x): G[0] = 31 - 1 = 30
  i=5 (c): M[1] = 30 + 16 + 0 = 46  (from gap, posBonus = 0)

rawScore = 46
maxScore = 2 × 16 + 10 × (2 + 1) = 32 + 30 = 62
normalizedScore = 46 / 62 ≈ 0.742
```

--------------------------------

### Highlight Traceback Pipeline

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/DAMERAU_LEVENSHTEIN.md

Illustrates the priority-ordered fallback chain for recovering matched character positions, starting from exact matches and falling back to edit distance for typos.

```plaintext
Query + Candidate → Normalize + Build Mapping → Prefix Check (dist == 0)
                                                       ↓ (no)
                                                 Substring Check (dist == 0)
                                                       ↓ (no)
                                                 Subsequence Alignment (greedy → DP)
                                                       ↓ (no)
                                                 Acronym Matching
                                                       ↓ (no)
                                                 ED Traceback (dist > 0, typos)
                                                       ↓
                                                 Map to String.Index → Coalesce Ranges
```

--------------------------------

### FuzzyMatch (ED) Score Differentiation Example

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/COMPARISON.md

Demonstrates how FuzzyMatch (ED) provides well-differentiated scores for exact matches, prefix variants, and substring matches. Observe the score values and rankings.

```text
Query: "BVB" (symbol)
  Rank 1: BVB Borussia Dortmund     score=1.0000  (exact match)
  Rank 2: BV1 B6 18 POBV1...        score=0.9376  (1-edit match, longer)
  Rank 3: BV1 B6 26 POBV1...        score=0.9376  (1-edit match, longer)

Query: "NVD" (symbol)
  Rank 1: NVD NVIDIA Corp           score=1.0000  (exact match)
  Rank 2: 3NVD Leverage Shares...   score=0.9526  (prefix variant, longer)
  Rank 3: 2NVD Leverage Shares...   score=0.9526  (prefix variant, longer)

Query: "DAX" (name)
  Rank 1: DAX Performance Index     score=0.9946  (exact prefix, high recovery)
  Rank 2: Deka DAX UCITS ETF        score=0.9910  (whole-word substring)
  Rank 3: Xtrackers DAX UCITS ETF   score=0.9880  (whole-word substring)
```

--------------------------------

### Smith-Waterman DP: Match Transition (From Gap)

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/SMITH_WATERMAN.md

Calculates the Match state (M[j]) transition when starting a new match after a gap. It uses the previous gap score and adds the match score and position bonus.

```pseudocode
if diagGap > 0:
    fromGap = diagGap + scoreMatch + posBonus[i]
```

--------------------------------

### Highlight Matched Characters with SwiftUI Attributes

Source: https://github.com/ordo-one/fuzzymatch/blob/main/README.md

Use `attributedHighlight()` to get a styled `AttributedString` for UI display. Call it only for visible results. This example uses SwiftUI attributes for styling.

```swift
import FuzzyMatch
import SwiftUI  // or just Foundation on Linux

let matcher = FuzzyMatcher()
let query = matcher.prepare("mod")

// Returns nil if no match — styled AttributedString otherwise
if let text = matcher.attributedHighlight("format:modern", against: query, applying: {
    $0.foregroundColor = .orange  // SwiftUI attribute
}) {
    // text has "mod" styled in orange, rest unstyled
}
```

--------------------------------

### Build and Test Commands

Source: https://github.com/ordo-one/fuzzymatch/blob/main/CONTRIBUTING.md

Standard commands for building the project, running tests, and executing benchmarks.

```bash
swift build              # Debug build
swift test               # Run all tests
swift package --package-path Benchmarks benchmark  # Run benchmark suite (release build)
```

--------------------------------

### Verify project build and tests

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Agents/SPANS_MIGRATION.md

Run the test suite and build the project in release mode to verify migration changes.

```bash
swift test && swiftlint lint
swift build -c release
swift build --package-path Benchmarks
swift build --package-path Comparison/bench-fuzzymatch
```

--------------------------------

### Build and Test Commands

Source: https://github.com/ordo-one/fuzzymatch/blob/main/CLAUDE.md

Standard Swift Package Manager commands for building, testing, and benchmarking the library.

```bash
swift build                    # Debug build
swift build -c release         # Release build
swift test                     # Run all tests
swift test --filter TestName   # Run specific test (e.g., --filter EditDistanceTests)
swift package --package-path Benchmarks benchmark  # Run benchmarks (builds release first)
```

--------------------------------

### FuzzyMatcher Initialization

Source: https://github.com/ordo-one/fuzzymatch/blob/main/README.md

Demonstrates how to initialize the FuzzyMatcher with different configurations.

```APIDOC
## FuzzyMatcher Initialization

### Description
Initialize the `FuzzyMatcher` with either the default configuration (Edit Distance) or the Smith-Waterman algorithm.

### Method
`init(config: MatchConfig)`

### Parameters
- **config** (`MatchConfig`) - Optional - The configuration for the matcher. Defaults to `.init()` which uses the Edit Distance algorithm.

### Request Example
```swift
// Default: Edit Distance (recommended for most use cases)
let matcher = FuzzyMatcher()

// Smith-Waterman mode
let matcher = FuzzyMatcher(config: .smithWaterman)
```
```

--------------------------------

### Generate DocC Documentation

Source: https://github.com/ordo-one/fuzzymatch/blob/main/CONTRIBUTING.md

Preview the project documentation locally using the Swift package manager.

```bash
swift package generate-documentation --target FuzzyMatch
```

--------------------------------

### Customizing Fuzzy Matching with Smith-Waterman

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Sources/FuzzyMatch/FuzzyMatch.docc/GettingStarted.md

Configures FuzzyMatcher to use Smith-Waterman local alignment mode with a custom gap start penalty.

```swift
// Smith-Waterman mode with custom gap penalty
let swConfig = MatchConfig(
    algorithm: .smithWaterman(SmithWatermanConfig(penaltyGapStart: 5))
)
let swMatcher = FuzzyMatcher(config: swConfig)
```

--------------------------------

### Use Convenience API

Source: https://github.com/ordo-one/fuzzymatch/blob/main/README.md

Methods for quick exploration and prototyping. Note that these methods allocate a new buffer per call.

```swift
let matcher = FuzzyMatcher()

// One-shot: prepare + score in a single call
if let match = matcher.score("getUserById", against: "usr") {
    print("Score: \(match.score)")
}

// Top-N: returns the best matches sorted by score
let query = matcher.prepare("config")
let top5 = matcher.topMatches(candidates, against: query, limit: 5)

// All matches: returns every match sorted by score
let all = matcher.matches(candidates, against: query)
```

--------------------------------

### Initialize Matchers and Highlight Matches

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/MATCHING_MODES.md

Demonstrates initializing both Edit Distance and Smith-Waterman matchers and using the highlight method to retrieve matched character ranges.

```swift
let matcher = FuzzyMatcher()           // ED mode
let swMatcher = FuzzyMatcher(config: .smithWaterman)

// Both modes use the same API
if let ranges = matcher.highlight("getUserById", against: "getuser") {
    // ranges covers "getUser" in "getUserById"
}

// ED mode handles typos — SW mode would return nil for this query
if let ranges = matcher.highlight("Berkshire", against: "Berkhsire") {
    // ranges covers "Berkshire" (transposition corrected)
}
```

--------------------------------

### Get Sorted Matches Using High-Performance API

Source: https://github.com/ordo-one/fuzzymatch/blob/main/README.md

Uses the high-performance, zero-allocation API for scoring and sorting matches. This is recommended for performance-critical applications.

```swift
let matcher = FuzzyMatcher()
let query = matcher.prepare("config")
var buffer = matcher.makeBuffer()

let candidates = ["configuration", "ConfigManager", "user_config", "settings"]

let results = candidates.compactMap { candidate -> (String, ScoredMatch)? in
    guard let match = matcher.score(candidate, against: query, buffer: &buffer) else {
        return nil
    }
    return (candidate, match)
}

let sorted = results.sorted { $0.1.score > $1.1.score }
for (candidate, match) in sorted {
    print("\(candidate): \(match.score)")
}
```

--------------------------------

### Build Project Harnesses

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Agents/PREPARE_RELEASE.md

Builds all project harnesses sequentially. This prevents concurrent build races.

```bash
swift build -c release --package-path Comparison/bench-fuzzymatch
```

```bash
(cd Comparison/bench-nucleo && cargo build --release)
```

```bash
make -C Comparison/bench-rapidfuzz
```

```bash
(cd Comparison/quality-fuzzymatch && swift build -c release)
```

```bash
(cd Comparison/quality-nucleo && cargo build --release)
```

```bash
make -C Comparison/quality-rapidfuzz
```

--------------------------------

### Get Raw Highlight Ranges

Source: https://github.com/ordo-one/fuzzymatch/blob/main/README.md

Use `highlight()` directly to obtain the raw ranges for manual styling. The returned ranges are coalesced and sorted.

```swift
if let ranges = matcher.highlight("format:modern", against: query) {
    // ranges: [Range<String.Index>] — coalesced and sorted
    var text = AttributedString("format:modern")
    for range in ranges {
        let start = AttributedString.Index(range.lowerBound, within: text)!
        let end = AttributedString.Index(range.upperBound, within: text)!
        text[start..<end].foregroundColor = .accentColor
    }
}
```

--------------------------------

### Run Performance and Quality Benchmarks

Source: https://github.com/ordo-one/fuzzymatch/blob/main/CONTRIBUTING.md

Execute performance comparison scripts and quality evaluation tools.

```bash
bash Comparison/run-benchmarks.sh --fm --nucleo --rf
python3 Comparison/run-quality.py --fm --nucleo --rf --fzf
```

--------------------------------

### Highlight Matched Characters with Foundation Attributes

Source: https://github.com/ordo-one/fuzzymatch/blob/main/README.md

Use `attributedHighlight()` for UI display with Foundation-level attributes when not using SwiftUI. This example applies bold styling.

```swift
if let text = matcher.attributedHighlight("format:modern", against: query, applying: {
    $0.inlinePresentationIntent = .stronglyEmphasized  // bold
}) {
    // text has "mod" in bold
}
```

--------------------------------

### Get All Fuzzy Matches

Source: https://context7.com/ordo-one/fuzzymatch/llms.txt

Retrieves all candidate strings that match a given query, sorted by score in descending order. No limit is applied to the number of results.

```swift
let matcher = FuzzyMatcher()
let query = matcher.prepare("config")

let candidates = [
    "appConfig", "configManager", "database", "userConfig",
    "settings", "serverConfiguration", "localConfig"
]

let allMatches = matcher.matches(candidates, against: query)

print("Found \(allMatches.count) matches:")
for result in allMatches {
    print("  \(result.candidate): \(result.match.score)")
}
```

--------------------------------

### Run Quick Benchmark Comparison

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Comparison/README.md

Perform a quick benchmark comparison focusing only on FuzzyMatch and nucleo. This is useful for rapid testing or when only these two libraries are of interest.

```bash
bash Comparison/run-benchmarks.sh --fm --nucleo
```

--------------------------------

### Validate Codebase

Source: https://github.com/ordo-one/fuzzymatch/blob/main/CLAUDE.md

Run the test suite and SwiftLint to ensure code quality and correctness.

```bash
swift test && swiftlint lint
```

--------------------------------

### Get Top N Fuzzy Matches

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Sources/FuzzyMatch/FuzzyMatch.docc/GettingStarted.md

Retrieves the top N matches for a given query against a list of candidates, sorted by score. This uses the convenience API.

```swift
let matcher = FuzzyMatcher()
let query = matcher.prepare("config")

// Or just the top 3
let top3 = matcher.topMatches(
    ["configuration", "ConfigManager", "user_config", "settings"],
    against: query,
    limit: 3
)
```

--------------------------------

### Run Full Benchmark Comparison

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Comparison/README.md

Execute a full comparison including FuzzyMatch in edit distance and Smith-Waterman modes, nucleo, and RapidFuzz. Ensure all specified flags are used for a comprehensive test.

```bash
bash Comparison/run-benchmarks.sh --fm --sw --nucleo --rf
```

--------------------------------

### Get All Fuzzy Matches Sorted by Score

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Sources/FuzzyMatch/FuzzyMatch.docc/GettingStarted.md

Retrieves all matches for a given query against a list of candidates and returns them sorted by their score in descending order. This uses the convenience API.

```swift
let matcher = FuzzyMatcher()
let query = matcher.prepare("config")

// Get all matches sorted by score
let sorted = matcher.matches(
    ["configuration", "ConfigManager", "user_config", "settings"],
    against: query
)
for result in sorted {
    print("\(result.candidate): \(result.match.score)")
}
```

--------------------------------

### Run Performance Benchmarks

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Agents/PREPARE_RELEASE.md

Executes performance benchmarks sequentially for different matchers and modes. Use --skip-build to avoid rebuilding.

```bash
bash Comparison/run-benchmarks.sh --fm-ed --skip-build
```

```bash
bash Comparison/run-benchmarks.sh --fm-sw --skip-build
```

```bash
bash Comparison/run-benchmarks.sh --fm-ed-utf8 --skip-build
```

```bash
bash Comparison/run-benchmarks.sh --fm-sw-utf8 --skip-build
```

```bash
bash Comparison/run-benchmarks.sh --nucleo --skip-build
```

```bash
bash Comparison/run-benchmarks.sh --rf-wratio --skip-build
```

```bash
bash Comparison/run-benchmarks.sh --rf-partial --skip-build
```

--------------------------------

### Get Sorted Matches Using Convenience API

Source: https://github.com/ordo-one/fuzzymatch/blob/main/README.md

Retrieves all matches sorted by score (highest first) using the `matches()` convenience method. This is suitable for typical UI display needs.

```swift
let matcher = FuzzyMatcher()
let query = matcher.prepare("config")

// Get all matches sorted by score (highest first)
let sorted = matcher.matches(
    ["configuration", "ConfigManager", "user_config", "settings"],
    against: query
)
for result in sorted {
    print("\(result.candidate): \(result.match.score)")
}
```

--------------------------------

### Smith-Waterman Configuration Usage

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/SMITH_WATERMAN.md

Shows how to initialize a FuzzyMatcher with default Smith-Waterman settings or with a custom configuration for fine-tuning parameters.

```swift
// Default Smith-Waterman mode
let matcher = FuzzyMatcher(config: .smithWaterman)

// Custom tuning
let custom = SmithWatermanConfig(
    scoreMatch: 20,
    penaltyGapStart: 5,
    penaltyGapExtend: 2,
    bonusConsecutive: 6,
    bonusBoundary: 10,
    bonusCamelCase: 7,
    bonusFirstCharMultiplier: 3
)
let config = MatchConfig(algorithm: .smithWaterman, smithWatermanConfig: custom)
let matcher = FuzzyMatcher(config: config)
```

--------------------------------

### Run Quality Comparison

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Agents/PREPARE_RELEASE.md

Executes quality comparison tests sequentially for different matchers. Use --skip-build to avoid rebuilding.

```python
python3 Comparison/run-quality.py --fm-ed --skip-build
```

```python
python3 Comparison/run-quality.py --fm-sw --skip-build
```

```python
python3 Comparison/run-quality.py --nucleo --skip-build
```

```python
python3 Comparison/run-quality.py --rf-wratio --skip-build
```

```python
python3 Comparison/run-quality.py --rf-partial --skip-build
```

```python
python3 Comparison/run-quality.py --fzf --skip-build
```

--------------------------------

### Smith-Waterman DP: Gap Transition

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/SMITH_WATERMAN.md

Calculates the Gap state (G[j]) in the Smith-Waterman DP. It determines the best score by either opening a new gap from a match state or extending an existing gap, using penalties for starting and extending gaps.

```pseudocode
G[j] = max(
    0,
    M[i-1,j] - penaltyGapStart,     // open a new gap from a match
    G[i-1,j] - penaltyGapExtend      // extend an existing gap
)
```

--------------------------------

### Run Performance Benchmarks

Source: https://github.com/ordo-one/fuzzymatch/blob/main/CLAUDE.md

Execute performance comparison scripts to evaluate FuzzyMatch against competitors like nucleo and RapidFuzz.

```bash
bash Comparison/run-benchmarks.sh --fm-ed --nucleo  # Quick: FuzzyMatch(ED) vs nucleo only
bash Comparison/run-benchmarks.sh                # Full: all matchers
```

```bash
bash Comparison/run-benchmarks.sh   # Performance comparison (nucleo, RapidFuzz, FuzzyMatch)
python3 Comparison/run-quality.py   # Quality comparison (FuzzyMatcher, nucleo, RapidFuzz, fzf)
```

--------------------------------

### Run Benchmark Comparison Including Ifrit

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Comparison/README.md

Include the Ifrit library in the benchmark comparison. Note that Ifrit is known for its slow runtime, so this command should be used cautiously.

```bash
bash Comparison/run-benchmarks.sh --ifrit
```

--------------------------------

### High-Performance Scoring with Prepared Queries

Source: https://context7.com/ordo-one/fuzzymatch/llms.txt

Prepare queries once and reuse buffers for zero-allocation scoring in performance-critical loops. This is recommended for large candidate sets.

```swift
let matcher = FuzzyMatcher()

// 1. Prepare the query once (precomputes bitmask, trigrams, etc.)
let query = matcher.prepare("getUser")

// 2. Create a reusable buffer (eliminates allocations in the scoring loop)
var buffer = matcher.makeBuffer()

// 3. Score candidates with zero heap allocations per call
let candidates = ["getUserById", "getUsername", "setUser", "fetchData", "userService"]
var results: [(String, Double)] = []

for candidate in candidates {
    if let match = matcher.score(candidate, against: query, buffer: &buffer) {
        results.append((candidate, match.score))
    }
}

// Sort by score descending
results.sort { $0.1 > $1.1 }
for (candidate, score) in results {
    print("\(candidate): \(score)")
}
// Output:
// getUserById: 0.9988...
// getUsername: 0.9988...
// setUser: 0.9047...
```

--------------------------------

### Run FuzzyMatcher fuzz target

Source: https://github.com/ordo-one/fuzzymatch/blob/main/README.md

Build and run the fuzz target for FuzzyMatcher. Press Ctrl-C to stop the execution. This command requires the open-source Swift toolchain on Linux.

```bash
bash Fuzz/run.sh run
```

--------------------------------

### Use Convenience API

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Sources/FuzzyMatch/FuzzyMatch.docc/GettingStarted.md

Perform quick string matching without manual buffer management.

```swift
import FuzzyMatch

let matcher = FuzzyMatcher()

// One-shot scoring — no buffer management needed
if let match = matcher.score("getUserById", against: "getUser") {
    print("score=\(match.score), kind=\(match.kind)")
}

// Top-N matches sorted by score
let query = matcher.prepare("config")
let top5 = matcher.topMatches(
    ["appConfig", "configManager", "database", "userConfig"],
    against: query,
    limit: 5
)

// All matches sorted by score
let all = matcher.matches(
    ["appConfig", "configManager", "database", "userConfig"],
    against: query
)
```

--------------------------------

### Build and Run Fuzzer - Bash

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/DAMERAU_LEVENSHTEIN.md

Builds and runs the libFuzzer target for FuzzyMatcher. Use Ctrl-C to stop execution. The release build is optimized for performance.

```bash
bash Fuzz/run.sh
```

```bash
bash Fuzz/run.sh run
```

--------------------------------

### Run Full Quality Comparison

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Comparison/README.md

Execute a full quality comparison involving FuzzyMatch in both edit distance and Smith-Waterman modes, nucleo, RapidFuzz, and fzf. This script analyzes the quality of matches across libraries.

```python
python3 Comparison/run-quality.py --fm --sw --nucleo --rf --fzf
```

--------------------------------

### Generate Test Files for fuzzygrep

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Agents/PREPARE_RELEASE.md

Creates large text files of varying sizes (10 million, 100 million, and 1 billion lines) for benchmarking. The 1 billion line file can take several minutes to generate.

```bash
{ echo "color"; awk 'BEGIN{for(i=1;i<=10000000;i++) print "line " i}'; echo "colour"; } > /tmp/fuzzygrep-10M.txt
{ echo "color"; awk 'BEGIN{for(i=1;i<=100000000;i++) print "line " i}'; echo "colour"; } > /tmp/fuzzygrep-100M.txt
{ echo "color"; awk 'BEGIN{for(i=1;i<=1000000000;i++) print "line " i}'; echo "colour"; } > /tmp/fuzzygrep-1B.txt
```

--------------------------------

### One-shot and Top-N Scoring with FuzzyMatcher

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Sources/FuzzyMatch/FuzzyMatch.docc/FuzzyMatch.md

Use the convenience API for prototyping or small candidate sets. The `score` method performs one-shot scoring, while `prepare` and `topMatches` are useful for finding the top N matches against a query.

```swift
import FuzzyMatch

let matcher = FuzzyMatcher()

// One-shot scoring
if let match = matcher.score("getUserById", against: "getUser") {
    print("score=\(match.score), kind=\(match.kind)")
}

// Top-N matching
let query = matcher.prepare("config")
let top3 = matcher.topMatches(
    ["appConfig", "configManager", "database", "userConfig"],
    against: query,
    limit: 3
)
```

--------------------------------

### Per-File Remark Summary

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Agents/ASSEMBLY_VISION.md

Generate a summary of optimization remarks for a specific file, showing the count of each remark type. This allows for focused analysis of optimization decisions within a particular source file.

```bash
grep "MyFile.swift" /tmp/av_output.txt | grep "remark:" | sed 's/.*remark: //' | sort | uniq -c | sort -rn
```

--------------------------------

### Run Microbenchmarks

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Agents/PREPARE_RELEASE.md

Executes microbenchmarks using Swift Package Manager. Update the microbenchmark table in README.md with the results.

```bash
swift package --package-path Benchmarks benchmark
```

--------------------------------

### Run fuzzygrep Benchmarks (Smith-Waterman)

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Agents/PREPARE_RELEASE.md

Executes benchmark tests for fuzzygrep using the Smith-Waterman mode. It tests the tool against files of 10 million, 100 million, and 1 billion lines, redirecting output to /dev/null. Use 'bash -c "time ..." 2>&1' for cleaner output when capturing results programmatically.

```bash
time .build/release/fuzzygrep 1235321 --sw -score 0.5 < /tmp/fuzzygrep-10M.txt > /dev/null
time .build/release/fuzzygrep 1235321 --sw -score 0.5 < /tmp/fuzzygrep-100M.txt > /dev/null
time .build/release/fuzzygrep 1235321 --sw -score 0.5 < /tmp/fuzzygrep-1B.txt > /dev/null
```

--------------------------------

### Run Specific Test Suite

Source: https://github.com/ordo-one/fuzzymatch/blob/main/CONTRIBUTING.md

Execute a specific test file using the Swift test filter.

```bash
swift test --filter EditDistanceTests
```

--------------------------------

### Create FuzzyMatcher Instances

Source: https://context7.com/ordo-one/fuzzymatch/llms.txt

Instantiate FuzzyMatcher with default or custom configurations. Use `.smithWaterman` for multi-word queries and higher throughput, or customize parameters like `minScore` and `maxEditDistance` for specific needs.

```swift
import FuzzyMatch

// Default configuration (edit distance, minScore: 0.3)
let matcher = FuzzyMatcher()

// Smith-Waterman mode for multi-word queries and higher throughput
let swMatcher = FuzzyMatcher(config: .smithWaterman)

// Custom edit distance configuration
let strictMatcher = FuzzyMatcher(config: MatchConfig(
    minScore: 0.7,
    algorithm: .editDistance(EditDistanceConfig(
        maxEditDistance: 1,
        prefixWeight: 2.0,
        substringWeight: 0.8,
        wordBoundary့Bonus: 0.15
    ))
))

// Custom Smith-Waterman configuration
let customSW = FuzzyMatcher(config: MatchConfig(
    algorithm: .smithWaterman(SmithWatermanConfig(
        penaltyGapStart: 8,
        bonusBoundary: 10,
        bonusCamelCase: 7
    ))
))
```

--------------------------------

### Initialize FuzzyMatcher

Source: https://github.com/ordo-one/fuzzymatch/blob/main/README.md

Configure the matcher using either the default Edit Distance algorithm or the Smith-Waterman mode.

```swift
// Default: Edit Distance (recommended for most use cases)
let matcher = FuzzyMatcher()

// Smith-Waterman mode
let matcher = FuzzyMatcher(config: .smithWaterman)
```

--------------------------------

### Build FuzzyMatcher fuzz target for debugging

Source: https://github.com/ordo-one/fuzzymatch/blob/main/README.md

Build a debug version of the fuzz target for FuzzyMatcher, enabling the use of lldb for debugging. This requires the open-source Swift toolchain on Linux.

```bash
bash Fuzz/run.sh debug run
```

--------------------------------

### Build FuzzyMatcher fuzz target

Source: https://github.com/ordo-one/fuzzymatch/blob/main/README.md

Build the release version of the fuzz target for FuzzyMatcher. This script is intended for Linux environments with the open-source Swift toolchain.

```bash
bash Fuzz/run.sh
```

--------------------------------

### Smith-Waterman DP: Match Transition (First Character)

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/SMITH_WATERMAN.md

Handles the Match state (M[j]) transition for the first character of the query (j=0). It initializes the score and bonus based on the match score, position bonus, and a first-character multiplier.

```pseudocode
if j == 0:
    // First query character: fresh alignment start
    M[j] = scoreMatch + posBonus[i] × firstCharMultiplier
    B[j] = posBonus[i]
```

--------------------------------

### Initialize FuzzyMatcher

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Documentation/MATCHING_MODES.md

Instantiate the matcher with either the default Edit Distance configuration or the Smith-Waterman configuration.

```swift
// Default: Edit Distance mode (recommended for most use cases)
let matcher = FuzzyMatcher()

// Smith-Waterman mode
let matcher = FuzzyMatcher(config: .smithWaterman)
```

--------------------------------

### Run fuzzygrep Benchmarks (Edit Distance)

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Agents/PREPARE_RELEASE.md

Executes benchmark tests for fuzzygrep using the default Edit Distance mode. It tests the tool against files of 10 million, 100 million, and 1 billion lines, redirecting output to /dev/null. Use 'bash -c "time ..." 2>&1' for cleaner output when capturing results programmatically.

```bash
time .build/release/fuzzygrep 1235321 -score 0.5 < /tmp/fuzzygrep-10M.txt > /dev/null
time .build/release/fuzzygrep 1235321 -score 0.5 < /tmp/fuzzygrep-100M.txt > /dev/null
time .build/release/fuzzygrep 1235321 -score 0.5 < /tmp/fuzzygrep-1B.txt > /dev/null
```

--------------------------------

### Highlight with Foundation Attributes

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Sources/FuzzyMatch/FuzzyMatch.docc/GettingStarted.md

Apply styling using Foundation-level attributes for non-SwiftUI environments.

```swift
if let text = matcher.attributedHighlight("format:modern", against: query, applying: {
    $0.inlinePresentationIntent = .stronglyEmphasized
}) {
    // text has "mod" in bold
}
```

--------------------------------

### Run Quality Comparison Including Ifrit

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Comparison/README.md

Include the Ifrit library in the quality comparison. Similar to benchmarks, Ifrit's inclusion may significantly increase runtime.

```python
python3 Comparison/run-quality.py --ifrit
```

--------------------------------

### High-Performance Scoring with FuzzyMatcher

Source: https://github.com/ordo-one/fuzzymatch/blob/main/Sources/FuzzyMatch/FuzzyMatch.docc/FuzzyMatch.md

For production use and interactive search, leverage the high-performance API for zero heap allocations per `score` call. This involves preparing the query and using a buffer for scoring.

```swift
let matcher = FuzzyMatcher()
let query = matcher.prepare("getUser")
var buffer = matcher.makeBuffer()

let candidates = ["getUserById", "getUsername", "setUser", "fetchData"]
for candidate in candidates {
    if let match = matcher.score(candidate, against: query, buffer: &buffer) {
        print("\(candidate): score=\(match.score), kind=\(match.kind)")
    }
}
// getUserById: score=0.9988, kind=prefix
// getUsername: score=0.9988, kind=prefix
// setUser: score=0.9047619047619048, kind=prefix
```