Vex代码搜索

Search by meaning (requires --semantic index)

vex search "payment processing" --semantic

Run (requires nightly)

RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_index_reader -- -max_total_time=120 RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_refs_fst -- -max_total_time=60 RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_symbol_fst -- -max_total_time=60 RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_bloom_load -- -max_total_time=60 RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_pattern_parser -- -max_total_time=60 RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_manifest_load -- -max_total_time=60 RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_marker_load -- -max_total_time=60 RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_tokenize_document -- -max_total_time=60 RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_hash_index_load -- -max_total_time=60 ```

Nine fuzz targets cover the reader's unsafe paths plus every text / sidecar parser that takes adversarial input:

Most recent system-wide audit (v1.14.1, 2026-06-05): 5,792,231 total iterations across all 9 targets in ~9 min wall-clock, zero crashes / panics / AddressSanitizer hits / leaks. Plus a focused 3,000,000- iter run on fuzz_hash_index_load alone — clean. Coverage saturated for the small binary-header parsers (bloom, marker, hash_index); JSON / grammar parsers still surfacing new features at saturation (fuzz_manifest_load reached cov:1355 ft:4191 / 1311 corpus, fuzz_pattern_parser cov:551 ft:3693 / 1210 corpus).

Fuzzing has found and fixed five real defects across the project life:

- v1.x: out-of-bounds read on crafted symbol_count, misaligned pointer dereference on odd symbols_offset, unchecked section offsets exceeding file size (binary reader hardening). - v1.12.0: SymbolBloom::load accepted a sidecar with n_bits = 0 + k_num = 0 whose consistency guard passed but later panicked inside bloomfilter::Bloom::check on hash % 0. Fix: reject degenerate sizes during load. - v1.12.0: SymbolBloom::load accepted k_num up to ~2.1B, which made every may_contain call loop for 110+ seconds (DoS, not a panic). Fix: cap k_num <= MAX_K_NUM = 64 at load time.

The v1.13.0 / v1.14.1 additions found no defects in fresh code — the review-driven MAX_COUNT guards on hash_index::save / load were added as defence-in-depth before the fuzzer ran (rust-reviewer + code-reviewer flagged the truncating as u32 cast on save), and the sustained 3M / 5.8M iteration runs confirmed they hold.

Installation

```bash

Install vex

brew tap tenatarika/tap && brew install vex

Source build (if you prefer or are on an unsupported triple)

cargo build --release -p vex-mcp

Install (once)

cargo install cargo-fuzz

Quick Start

```bash

Find all usages of a symbol

vex usages "IndexReader"

Usages (FST)

References stored in an FST (Finite State Transducer) — zero-copy lookup from mmap with prefix search support.

rg: 20 matches across imports, usage sites, comments, tests (2,045 chars)

$ rg -w "PreAggregatedConfig" . ./models.py:3602:class PreAggregatedConfig(models.Model): ./models.py:3610: pre_aggregated_config = PreAggregatedConfig.objects.get(...) ./serializers.py:48:from .models import PreAggregatedConfig ./tests.py:12: config = PreAggregatedConfig(...) ... (16 more lines)

Bundle: 4 round-trips → 1 envelope (v1.9, Phase 13.2)

vex bundle --mode symbol --symbol PaymentService # body + callers + callees + similar vex bundle --mode pr-impact --base origin/main # changed symbols + transitive callers + tests vex bundle --mode project --top-n 30 # top-N by reverse call-graph indegree

Configuration

Create a .vex.toml in your project root to customize vex behavior:

vex init  # generates .vex.toml with commented defaults

```toml

"text" (verbose multi-line), or "json" (envelope for MCP / tools).

JSON envelope (for MCP / tool integration; what `vex-mcp` parses)

vex search "Foo" --format json ```

Pin a different default in .vex.toml via format = "text" if you want the verbose multi-line view at the terminal.

JSON envelope (v1.11.0 — BREAKING for bare-array parsers)

Every --format json subcommand wraps its payload in the Phase 13 envelope. Single shape, easy to detect via protocol_version:

{
  "protocol_version": "v1",
  "capabilities": { /* see `vex capabilities` */ },
  "_meta": { "vex.dev/index_age_ms": 1200, "ttlMs": 30000, "cacheScope": "project" },
  "results": [ /* the actual data, shape depends on the subcommand */ ]
}

Pre-v1.11 only search and bundle returned this envelope; the other ~14 subcommands (show, usages, pattern, grep, implementations, callers, callees, paths, reachable, check, similar, duplicates, diff, outline, index, update, status, eval) emitted bare arrays / objects. Migration: pre-1.11 jq '.[0].name' or data[0]['name'] now needs jq '.results[0].name' / data['results'][0]['name']. Detect the envelope via response.get('protocol_version') == 'v1' to support both shapes during a rollout window.

Add to Claude Code MCP config (~/.claude/claude_desktop_config.json)

{ "mcpServers": { "vex": { "command": "/path/to/vex-mcp", "env": { "VEX_ROOT": "/path/to/your/project" } } } } ```

MCP Tools (23): - search — 3-way hybrid (structural + BM25 + semantic); accepts filter / include / exclude / kind / context_path / no_bm25 / --why / metadata filters / diff-scope (since / since_branched / changed_only) - find_symbol — exact name lookup - find_similar — semantic search by free-form description - similar — nearest neighbors of an existing symbol (explain adds Jaccard + diff); diff-scope - duplicates — near-duplicate symbol pairs (explain shows what differs); diff-scope - show — extract symbol body from source; Phase 13.3 truncation flags (signature_only / head / no_body / collapsed, mutually exclusive) - outline — file structure - usages — find all references to a symbol; filter / --strict / --why - grep — regex content search - pattern — AST pattern matching with metavar back-references; diff-scope; --why - implementations — find types extending a base class/trait/interface (incl. generics); diff-scope - callers / callees — direct callgraph navigation (fast path via persistent index); diff-scope - paths — enumerate caller chains between two functions - reachable — transitive callers of a target - diff — symbol-level diff between a git revision and the working tree - check — fast symbol existence check - bundle — unified multi-source bundle (mode: symbol | pr-impact | project), Phase 13 envelope - eval — ranking-evaluation harness (bench / min_ndcg), MCP defaults json: true so agents get a structured EvalReport - capabilities — machine-readable capability matrix (protocol_version, signals, bundle_modes, etc.) - index / update — build/rebuild index - status — index statistics

MCP ↔ CLI parity (v1.10): the schemas now mirror the CLI surface for every path-aware tool. Glob filters (include / exclude), substring filter, kind boost, context_path proximity hint, no_bm25, Phase 13.3 truncation, diff-scope, and no_stale_check are exposed everywhere the CLI accepts them — agents no longer need to drop to bash for "Rust files under crates/api/ since main"-style scoping.

The schemas follow a canonical vocabulary (query / symbol / symbols / path / pattern / filter / include / exclude); pre-v1.7 aliases (name, file, names, etc.) still work and emit _meta.deprecated_args: [...] in the JSON-RPC response. Malformed JSON-RPC input now returns the spec-compliant -32700 Parse error response (v1.9.2 fix) with a 512-codepoint echo of the offending line in the data field; broken-pipe / EOF on stdin cleanly shuts down the server instead of dropping in-flight tool calls. See docs/MCP-SCHEMA.md.

Find implementations of a trait/interface

vex implementations "Iterator"

Interface OR class with the same name

vex pattern 'interface $N || class $N' --lang typescript

Claude Code (CLI Integration)

The recommended way to integrate vex with Claude Code is via CLAUDE.md rules (see below). Vex runs as a CLI tool — Claude Code calls it directly via Bash, no MCP server needed.

Setup:

```bash

Integration

Shell Integration

```bash

CLAUDE.md Integration

Add this to your project's CLAUDE.md to make Claude Code use vex instead of grep:

```markdown

Unit & Integration Tests

cargo test                    # 1973 tests — unit, integration, property-based, adversarial
cargo clippy -- -D warnings   # zero warnings policy

Test coverage includes: - Per-language grammar regression (NEW): tests/<lang>_query_test.rs for all 19 supported languages — catches ABI mismatches and AST node renames when a tree-sitter grammar crate is upgraded - Binary format: roundtrip, corrupted/truncated/wrong-version rejection, out-of-bounds access, string pool dedup, empty index - Adversarial format: 20 crafted index tests — overflow offsets, bad magic/version, alignment attacks, truncated records - Vectors: write/read roundtrip for 384-dim f32 embeddings - FST: refs FST roundtrip, prefix search, symbol FST exact/prefix/fuzzy search - Search: structural, fuzzy (Levenshtein), RRF fusion, reranking with kind/path/proximity boosts - Reranking stress: NaN/Infinity/zero scores, 10K results, edge context paths - Property-based (proptest): rerank preserves length, sorted output, no NaN/negative scores, fusion commutativity - Incremental update: unchanged reuse, deleted removal, file rename, symbol move between files, empty file - Concurrency: parallel index/update (lock serialization), concurrent readers, read during reindex - Multi-language: Rust, Python, Go, Kotlin, TypeScript, C++, cross-language same-name, wrong extension, 1K-symbol file, deep nesting, error recovery - Unicode: BOM, mixed CRLF, unicode identifiers, null bytes, empty/whitespace files - Path edges: spaces in paths, deep nesting (20 levels), symlinks, absolute vs relative, Windows backslashes - Callgraph: callers/callees for Rust, Python, Go, TypeScript, Java - Persistent call graph (v1.5): format v4 roundtrip, callers/callees FST lookup, dedup, same-name-across-files isolation, same-name-within-file disambiguation, incremental update preserves edges, fallback to live scan for v3 - Similar/duplicates (v1.5): self-exclusion, threshold filtering, canonical pair dedup, body-length filter, empty-index handling - Pluggable embedder (v1.5): registry lookup, mismatch detection (incl. back-compat for pre-9.1 manifests), config + CLI priority, writer variable vector_dim - BM25 channel (v1.5): writer/reader roundtrip, pipeline emission, IDF discrimination, short-doc preference, 3-way RRF with Hybrid labeling, MatchType tagging, unicode tokens - Staleness: git HEAD comparison, dirty file detection, mtime fallback

How It Compares

Note: vex search speed assumes a pre-built index. Ripgrep and ast-grep require no upfront indexing and work immediately on any directory. The tradeoff is amortized: if you search the same codebase many times (typical in agent workflows), the one-time indexing cost pays for itself.

Best for: fast symbol search in AI agent workflows where token efficiency matters. Not a replacement for LSP-based tools (no refactoring, no go-to-definition in dependencies).

Search: vex vs ast-index vs ripgrep

Medium project (31K lines Rust, avg 10 runs)

Large project (20K symbols, Python/JS/SQL, avg 10 runs)

Key takeaway: vex search is constant ~4 ms (FST O(query_len)), regardless of project size — but this assumes a pre-built index. The comparison with ripgrep is not apples-to-apples: rg scans raw text with no indexing, while vex looks up a pre-built index. The real advantage is amortized: vex returns only symbol definitions (precise, token-efficient), while rg returns all text occurrences (noisy, expensive in LLM contexts).

HNSW vs Brute-Force (semantic vector search)

Semantic search embeds the query via ONNX (~55ms) then searches stored vectors. HNSW (usearch) replaces brute-force O(N) scan with O(log N) approximate nearest neighbor search:

HNSW stays constant ~3ms regardless of index size. Brute-force grows linearly. Total semantic search latency is dominated by ONNX embedding (~55ms), so end-to-end speedup is modest for small codebases but critical at scale.

Troubleshooting