searchfox-cli 0.1.0

CLI for https://searchfox.org
searchfox-cli-0.1.0 is not a library.

searchfox-cli

A command-line interface for searching Mozilla codebases using searchfox.org, written by and for Claude Code.

Features

  • Search across multiple Mozilla repositories (mozilla-central, autoland, beta, release, ESR branches, comm-central)
  • Support for regular expressions and case-sensitive search
  • Filter results by file path patterns (or search for files by path alone)
  • Language filtering: Filter results by programming language (C++, C, WebIDL, JavaScript)
  • Fetch and display file contents directly from GitHub
  • Complete function and class extraction: Intelligently extracts entire method/function bodies and class definitions with brace matching
  • Symbol search: Uses searchfox's native symbol indexing for precise symbol lookups
  • Advanced definition finding: Uses searchfox's structured data for reliable symbol resolution, prioritizes class definitions
  • Request logging: Detailed HTTP request timing and performance analysis
  • Configurable result limits

Installation

cargo install --path .

Usage

Basic Search

# Search for "AudioStream" in mozilla-central
searchfox-cli -q AudioStream

# Search with case sensitivity
searchfox-cli -q AudioStream -C

# Search with regular expressions
searchfox-cli -q '^Audio.*' -r

# Limit results to 10 matches
searchfox-cli -q AudioStream -l 10

Symbol and Definition Search

# Find symbol definitions
searchfox-cli --symbol AudioContext

# Find exact identifier matches (not prefix-based)
searchfox-cli --id main

# Search for symbols using searchfox's symbol index
searchfox-cli --symbol 'AudioContext'
searchfox-cli --symbol 'CreateGain'

# Search for symbols in specific paths
searchfox-cli -q 'path:dom/media symbol:AudioStream'

Repository Selection

# Search in autoland repository
searchfox-cli -q AudioStream -R autoland

# Search in beta branch
searchfox-cli -q AudioStream -R mozilla-beta

Path Filtering

# Search only in dom/media directory
searchfox-cli -q AudioStream -p ^dom/media

# Search in specific file patterns
searchfox-cli -q AudioStream -p '\.cpp$'

# Use -p alone to search for files by path pattern
searchfox-cli -p PContent.ipdl
searchfox-cli -p AudioContext.cpp

# Using advanced path syntax in query
searchfox-cli -q 'path:dom/media AudioStream'
searchfox-cli -q 'pathre:^dom/(media|audio) AudioStream'

Language Filtering

Filter search results by programming language using language-specific flags:

# Search only in C++ files (.cc, .cpp, .h, .hh, .hpp)
searchfox-cli -q AudioContext --cpp
searchfox-cli --define AudioContext -p dom/media --cpp

# Search only in C files (.c, .h)
searchfox-cli -q malloc --c

# Search only in WebIDL files (.webidl)
searchfox-cli -q AudioContext --webidl

# Search only in JavaScript files (.js, .mjs, .ts, .cjs, .jsx, .tsx)
searchfox-cli -q AudioContext --js

# Without language filters, all file types are included
searchfox-cli --define AudioContext -p dom/media

Advanced Query Features

# Search with context lines
searchfox-cli -q AudioStream --context 3

# Text search with regex
searchfox-cli -q 're:AudioContext::.*Create'

# Exact text search (escapes regex chars)
searchfox-cli -q 'text:function main()'

# Combined advanced queries
searchfox-cli -q 'context:3 pathre:dom/media symbol:AudioStream'

Symbol Search

The --symbol flag uses searchfox's native symbol indexing for precise symbol lookups:

# Search for symbols by name
searchfox-cli --symbol 'AudioContext'
searchfox-cli --symbol 'CreateGain'

# Combine with path filtering
searchfox-cli -q 'path:dom/media symbol:AudioStream'

Symbol search relies on searchfox's own symbol database, which includes properly mangled C++ symbols and other language constructs as indexed by the searchfox infrastructure.

Advanced Definition Finding

The --define flag provides an advanced way to find symbol definitions by:

  1. Symbol Search: Uses id: prefix internally for precise symbol lookups
  2. Class/Struct Priority: Prioritizes class and struct definitions over constructors
  3. Definition Resolution: Searches both "Definitions" and "Declarations" categories (for C++ classes)
  4. Context Extraction: Fetches the source file and displays the complete method/function/class
# Find class definition with full body
searchfox-cli --define AudioContext -p dom/media

# Find method definition with full context
searchfox-cli --define 'AudioContext::CreateGain'

# Filter by language
searchfox-cli --define AudioContext -p dom/media --cpp

# The tool will:
# 1. Search using id:AudioContext for precise matches
# 2. Prioritize class definitions over constructor declarations
# 3. Extract the complete class body (with brace matching)
# 4. Display the full definition with proper highlighting

This approach leverages searchfox's comprehensive symbol database for reliable definition finding.

Example Output:

For class definitions:

$ searchfox-cli --define AudioContext -p dom/media --cpp
>>>  135: class AudioContext final : public DOMEventTargetHelper,
     136:                            public nsIMemoryReporter,
     137:                            public RelativeTimeline {
     138:   AudioContext(nsPIDOMWindowInner* aParentWindow, bool aIsOffline,
     139:                uint32_t aNumberOfChannels = 0, uint32_t aLength = 0,
     140:                float aSampleRate = 0.0f);
     141:   ~AudioContext();
     142: 
     143:  public:
     144:   typedef uint64_t AudioContextId;
     145: 
     146:   NS_DECL_ISUPPORTS_INHERITED
     147:   NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(AudioContext, DOMEventTargetHelper)
     148:   MOZ_DEFINE_MALLOC_SIZE_OF(MallocSizeOf)
     ...
     335:   void RegisterNode(AudioNode* aNode);
   ...  : (method too long, truncated)

For method definitions:

$ searchfox-cli --define 'AudioContext::CreateGain'
>>>  469: already_AddRefed<GainNode> AudioContext::CreateGain(ErrorResult& aRv) {
     470:   return GainNode::Create(*this, GainOptions(), aRv);
     471: }

The tool automatically:

  • Searches searchfox's structured data for definition entries
  • Uses searchfox's native symbol indexing for accurate results
  • Finds the actual source file location (not generated binding files)
  • Fetches the source code and displays complete methods/functions
  • Highlights the exact definition line with >>>

Complete Function and Class Extraction

When using --define, the tool automatically detects and extracts complete function/method bodies and class definitions using intelligent brace matching:

For simple functions:

$ searchfox-cli --define 'AudioContext::CreateGain'
>>>  469: already_AddRefed<GainNode> AudioContext::CreateGain(ErrorResult& aRv) {
     470:   return GainNode::Create(*this, GainOptions(), aRv);
     471: }

For complex constructors with initializer lists:

$ searchfox-cli --define 'AudioContext::AudioContext'
>>>  154: AudioContext::AudioContext(nsPIDOMWindowInner* aWindow, bool aIsOffline,
     155:                            uint32_t aNumberOfChannels, uint32_t aLength,
     156:                            float aSampleRate)
     157:     : DOMEventTargetHelper(aWindow),
     158:       mId(gAudioContextId++),
     159:       mSampleRate(GetSampleRateForAudioContext(
     160:           aIsOffline, aSampleRate,
     161:           aWindow->AsGlobal()->ShouldResistFingerprinting(
     162:               RFPTarget::AudioSampleRate))),
     163:       mAudioContextState(AudioContextState::Suspended),
     164:       ...
     179:       mSuspendedByChrome(nsGlobalWindowInner::Cast(aWindow)->IsSuspended()) {
     180:   bool mute = aWindow->AddAudioContext(this);
     181:   // ... full method body continues ...
     205: }

Features of complete extraction:

  • Multi-language support: Handles C++, Rust, and JavaScript function syntax
  • Class and struct definitions: Extracts complete class/struct bodies with proper brace matching
  • Smart brace matching: Ignores braces in strings, comments, and character literals
  • Complex signatures: Handles multi-line function signatures and initializer lists
  • Constructor support: Properly extracts C++ constructors with member initialization lists
  • Class termination: Handles classes/structs ending with semicolons correctly
  • Safety limits: Truncates extremely long definitions (>200 lines) to prevent output overflow
  • Accurate parsing: Correctly handles nested braces, escape sequences, and comment blocks

Request Logging and Performance Analysis

The --log-requests flag enables comprehensive HTTP request logging for performance analysis and infrastructure planning:

# Enable detailed request logging
searchfox-cli --log-requests --define 'AudioContext::CreateGain'

Features:

  • Baseline latency measurement: HTTP HEAD request to searchfox.org for baseline timing
  • Request tracking: Each HTTP request gets a unique ID for correlation
  • Detailed timing: Start/end timestamps with duration in milliseconds
  • Response metrics: HTTP status codes and response size in bytes
  • Performance insights: Compare request times against baseline to identify bottlenecks

Example output:

=== REQUEST LOGGING ENABLED ===
[PING] Testing network latency to searchfox.org (ICMP ping disabled, using HTTP HEAD)...
[PING] HTTP HEAD latency: 573ms (HTTP 200 OK)
[PING] Note: This includes minimal server processing time, not just network latency
================================

[REQ-1] GET https://searchfox.org/mozilla-central/search?q=AudioContext%3A%3ACreateGain - START
[REQ-1] GET https://searchfox.org/mozilla-central/search?q=AudioContext%3A%3ACreateGain - END (573ms, 1188 bytes, HTTP 200)
[REQ-2] GET https://raw.githubusercontent.com/mozilla/firefox/main/dom/media/webaudio/AudioContext.cpp - START  
[REQ-2] GET https://raw.githubusercontent.com/mozilla/firefox/main/dom/media/webaudio/AudioContext.cpp - END (172ms, 44915 bytes, HTTP 200)

Performance analysis insights:

  • Network vs. server processing: Compare request duration against baseline latency
  • Service comparison: GitHub file fetching vs. searchfox API performance
  • Infrastructure planning: Determine if searchfox server upgrades would help vs. network optimization
  • Request patterns: Track multiple requests to identify consistency and variation

File Retrieval

# Fetch and display a specific file
searchfox-cli --get-file dom/media/AudioStream.h

Available Repositories

  • mozilla-central (default) - Main Firefox development
  • autoland - Integration repository
  • mozilla-beta - Beta release branch
  • mozilla-release - Release branch
  • mozilla-esr115 - ESR 115 branch
  • mozilla-esr128 - ESR 128 branch
  • mozilla-esr140 - ESR 140 branch
  • comm-central - Thunderbird development

Command Line Options

  • -q, --query <QUERY> - Search query string (supports advanced syntax)
  • -R, --repo <REPO> - Repository to search in (default: mozilla-central)
  • -p, --path <PATH> - Filter results by path prefix using regex, or search for files by path pattern
  • -C, --case - Enable case-sensitive search
  • -r, --regexp - Enable regular expression search
  • -l, --limit <LIMIT> - Maximum number of results to display (default: 50)
  • --get-file <FILE> - Fetch and display contents of a specific file
  • --symbol <SYMBOL> - Search for symbol definitions using searchfox's symbol index
  • --id <IDENTIFIER> - Search for exact identifier matches
  • --context <N> - Show N lines of context around matches
  • --define <SYMBOL> - Find and display the definition of a symbol with full context
  • --log-requests - Enable detailed HTTP request logging with timing and size information
  • --cpp - Filter results to C++ files only (.cc, .cpp, .h, .hh, .hpp)
  • --c - Filter results to C files only (.c, .h)
  • --webidl - Filter results to WebIDL files only (.webidl)
  • --js - Filter results to JavaScript files only (.js, .mjs, .ts, .cjs, .jsx, .tsx)

Examples

# Find all AudioStream references
searchfox-cli -q AudioStream

# Find function definitions starting with "Audio"
searchfox-cli -q '^Audio.*' -r

# Search only in media-related files
searchfox-cli -q AudioStream -p ^dom/media

# Get a specific file
searchfox-cli --get-file dom/media/AudioStream.h

# Search in Thunderbird codebase
searchfox-cli -q "MailServices" -R comm-central

# Find where AudioContext is defined
searchfox-cli --symbol AudioContext

# Find exact matches for "main" function
searchfox-cli --id main

# Search with context lines
searchfox-cli -q AudioStream --context 5

# Symbol search using searchfox's symbol index
searchfox-cli --symbol 'AudioContext'
searchfox-cli --symbol 'CreateGain'

# Find complete definition with context
searchfox-cli --define 'AudioContext::CreateGain'
searchfox-cli --define 'AudioContext'

# Language filtering
searchfox-cli --define AudioContext -p dom/media --cpp
searchfox-cli -q malloc --c
searchfox-cli -q AudioContext --js

# File path search
searchfox-cli -p PContent.ipdl
searchfox-cli -p AudioContext.cpp

# Advanced query syntax
searchfox-cli -q 'path:dom/media symbol:AudioStream'
searchfox-cli -q 're:AudioContext::.*Create'

# Performance analysis with request logging
searchfox-cli --log-requests --define 'AudioContext::CreateGain'
searchfox-cli --log-requests -q AudioStream -l 10

Dependencies

  • clap - Command line argument parsing
  • reqwest - HTTP client
  • tokio - Async runtime
  • serde - Serialization/deserialization
  • anyhow - Error handling

License

Licensed under either of

at your option.