CodeSearch

Fast, intelligent code search and analysis for 48+ programming languages.

Find what you need in seconds: functions, classes, duplicates, dead code, complexity issues.

Why CodeSearch?

Stop Wasting Time Searching Code

Problem: You're working in a large codebase and need to:

• Find where authentication logic is implemented
• Identify all usages of a deprecated function before refactoring
• Track down technical debt (TODOs, FIXMEs) scattered across files
• Understand complex function relationships and dependencies
• Find duplicated code that violates DRY principles
• Spot overly complex functions that need refactoring

Traditional tools fall short:

• grep is slow and doesn't understand code structure
• IDE search is limited to single projects/languages
• Manual code review is time-consuming and error-prone

CodeSearch solves these problems:

# Find authentication logic instantly
codesearch "authenticate" ./src --rank
# Result: All authentication code, ranked by relevance

# Track technical debt before sprint planning
codesearch deadcode ./src --format csv --output debt.csv
# Result: 15 unused functions, 23 TODOs, 8 unreachable blocks

# Find duplicates before they become maintenance nightmares
codesearch duplicates ./src
# Result: 12 code clones (80%+ similarity)

What Makes CodeSearch Different?

Unlike Joern (CPG graph DB, Scala queries, security research) or CodeQL (QL logic language, GitHub extractors, path queries), CodeSearch needs no indexing or config—and beats them on time-to-result:

• Unified graph (codesearch graph unified) — AST+CFG+DFG in one, like Joern's CPG but no DB
• Data-flow trace (codesearch flow <var>) — path-style tracing without extractors
• Security scan (codesearch security) — eval/exec/SQL patterns instantly
• First result — sub-second vs. minutes of import/build

See docs/CAPABILITY_REDESIGN.md for full comparison.

Real-World Impact

• Save Hours per Week: Replace manual code hunting with instant searches
• Ship Better Code: Catch dead code and complexity issues before review
• Understand Faster: Visualize code relationships with graph analysis
• Reduce Technical Debt: Track and eliminate code quality issues systematically

Quick Start

Installation

# Clone and build
git clone https://github.com/yingkitw/codesearch.git
cd codesearch
cargo build --release

# The binary will be at: ./target/release/codesearch
# Optional: Add to PATH
export PATH="$PATH:$PWD/target/release"

Basic Usage

# Simple search - find anything in your codebase
codesearch "function" ./src

# Search with file type filter
codesearch "class" ./src --extensions rs,py

# Fuzzy search (handles typos!)
codesearch "calcualtor" ./src --fuzzy

# Interactive mode
codesearch interactive

Usage Examples

1. Everyday Search Tasks

Find Function Definitions

# Find all functions named "process"
codesearch "fn process" ./src --extensions rs

# Find class definitions
codesearch "class User" ./src --extensions py

# Find async functions
codesearch --regex "async\s+fn\s+\w+" ./src --extensions rs

Track Technical Debt

# Find all TODOs and FIXMEs
codesearch "TODO\|FIXME" ./src

# Export to CSV for tracking
codesearch "TODO" ./src --format csv --output todos.csv

Refactor Safely

# Find all usages before refactoring
codesearch "old_function_name" ./src

# Case-sensitive search for exact matches
codesearch "MyStruct" ./src --case-sensitive

2. Code Quality Analysis

Health Score

# Get overall code health score
codesearch health ./src

# Output:
# 🏥 Code Health Report
# Overall Health Score: 85/100 ✅
# 
# Components:
#   • Dead Code: 90/100 (3 issues)
#   • Duplicates: 95/100 (2 duplicates)
#   • Complexity: 70/100 (5 high-complexity functions)

# CI/CD integration with fail threshold
codesearch health ./src --fail-under 80

Detect Dead Code

# Find unused code
codesearch deadcode ./src

# Output:
# ⚠️ Found 12 potential dead code items:
#    [var] L 10: variable 'unused_var'
#    [∅] L 42: empty_helper()
#    [?] L 58: TODO marker
#    [!] L 72: unreachable code

# Export for code review
codesearch deadcode ./src --format markdown --output review.md

Analyze Complexity

# Find complex functions that need refactoring
codesearch complexity ./src

# Output:
# 📊 Files by Complexity:
#   src/auth.rs: Cyclomatic 45, Cognitive 38 (HIGH)
#   src/parser.rs: Cyclomatic 28, Cognitive 22 (MEDIUM)

# Comprehensive code metrics
codesearch analyze ./src --metrics

Find Code Duplicates

# Identify copy-pasted code
codesearch duplicates ./src

# Output:
# 🔍 Found 8 duplicate code blocks:
#   auth.rs:120-145 vs user.rs:89-114 (85% similar)

3. Understanding Codebases

Codebase Overview

# Get high-level metrics
codesearch analyze ./src

# Output:
# Overview
#   Total files: 156
#   Total lines: 45,230
#   Languages: Rust (60%), Python (25%), TypeScript (15%)
#   Functions: 892
#   Classes: 124

Explore Function Relationships

# Generate call graph
codesearch callgraph ./src --format text

# Output:
# Call Graph Analysis:
#   Functions: 28
#   Function calls: 156
#   Recursive: authenticate()
#   Dead (never called): legacy_auth()

Control Flow Analysis

# Understand execution paths
codesearch graph cfg ./src/auth.rs --format text

# Shows: Basic blocks, branches, loops, unreachable code

Unified Graph (CPG-style, no DB)

# AST + CFG + DFG in one—like Joern's CPG, instant
codesearch graph unified ./src/main.rs

# Output: Syntax edges, execution edges, data edges

Data-Flow Trace (path-query style)

# Trace variable flow—no extractors, no indexing
codesearch flow input ./src --sink eval

Security Pattern Scan

# Instant security checks—eval, exec, SQL concat, etc.
codesearch security ./src --extensions js,py,php

4. Advanced Workflows

Interactive Mode

codesearch interactive

# Commands in interactive mode:
# authenticate       - Search for "authenticate"
# /f                 - Toggle fuzzy matching
# /i                 - Toggle case sensitivity
# analyze            - Show codebase metrics
# complexity         - Show complexity analysis
# deadcode           - Find dead code
# help               - Show all commands

Search with Ranking

# Get results ranked by relevance
codesearch "auth" ./src --rank

# Best match first:
#   src/auth/mod.rs:10 - pub fn authenticate() { ... }
#   src/user.rs:45     - fn check_auth() { ... }

Export Results

# CSV for spreadsheets
codesearch "TODO" ./src --format csv --output todos.csv

# Markdown for documentation
codesearch analyze ./src --format markdown --output analysis.md

# JSON for automation
codesearch "function" ./src --format json | jq '.matches'

5. Special Features

Search Git History

# Search through commit history
codesearch git-history "TODO" ./src

Search Remote Repositories

# Search GitHub/GitLab without cloning
codesearch remote --github "pattern" owner/repo

Build Index for Large Codebases

# Incremental indexing for faster searches
codesearch index ./src

# Watch for changes and auto-update
codesearch watch ./src

Common Commands Reference

Search Commands

codesearch "<query>" [path] [options]

# Options:
--extensions, -e     # Filter by file extensions (e.g., rs,py,js)
--case-sensitive     # Case-sensitive matching
--fuzzy              # Fuzzy matching (handles typos)
--regex              # Use regular expressions
--rank               # Rank results by relevance
--format             # Output format (text, csv, markdown, json)
--output, -o         # Output file path

Analysis Commands

codesearch health [path]            # Overall health score
codesearch deadcode [path]          # Find unused code
codesearch complexity [path]        # Analyze complexity
codesearch duplicates [path]        # Find duplicates
codesearch analyze [path]            # Codebase metrics
codesearch circular [path]          # Circular dependencies
codesearch design-metrics [path]    # Coupling & cohesion

Graph Commands

codesearch ast [file]               # Abstract Syntax Tree
codesearch cfg [file]               # Control Flow Graph
codesearch dfg [file]               # Data Flow Graph
codesearch callgraph [path]         # Call Graph
codesearch depgraph [path]          # Dependency Graph
codesearch pdg [file]               # Program Dependency Graph
codesearch graph-all [file]         # All graph types

Utility Commands

codesearch files [path]             # List searchable files
codesearch languages                # List supported languages
codesearch interactive              # Interactive mode
codesearch index [path]             # Build index
codesearch watch [path]             # Watch for changes
codesearch git-history <query>      # Search git history
codesearch remote --github <query>  # Search GitHub

Real-World Examples

Example 1: Pre-Code Review Checklist

#!/bin/bash
# review.sh - Automated code review checklist

echo "=== Code Review Report ==="
echo ""

echo "1. Dead Code Issues:"
codesearch deadcode ./src --format markdown

echo ""
echo "2. Complexity Issues:"
codesearch complexity ./src --threshold 15

echo ""
echo "3. Duplicate Code:"
codesearch duplicates ./src

echo ""
echo "4. Technical Debt:"
codesearch "TODO\|FIXME\|HACK" ./src

Example 2: Learning a New Codebase

# Step 1: Understand the structure
codesearch analyze ./src

# Step 2: Find entry points
codesearch --regex "(main|Main|app\.start)" ./src

# Step 3: Explore key modules
codesearch files ./src --extensions rs | head -20

# Step 4: Understand function relationships
codesearch callgraph ./src --format text | head -50

# Step 5: Find complex code to review
codesearch complexity ./src --sort | head -10

Example 3: Refactoring Workflow

# Before refactoring, find all usages
codesearch "OldAuthService" ./src --output old_usage.txt

# Check for complexity issues
codesearch complexity ./src/auth --format markdown > complexity_report.md

# Find similar code that could be consolidated
codesearch duplicates ./src/auth --output duplicates.txt

# After refactoring, verify no old code remains
codesearch "OldAuthService" ./src
# Should return: "No matches found"

Example 4: Continuous Quality Monitoring

# Add to CI/CD pipeline

# Fail if high complexity functions detected
complexity=$(codesearch complexity ./src --format json)
max_cc=$(echo "$complexity" | jq '.max_complexity')
if [ "$max_cc" -gt 20 ]; then
    echo "❌ High complexity detected: $max_cc"
    exit 1
fi

# Fail if new dead code introduced
deadcode_count=$(codesearch deadcode ./src --format json | jq '.total')
if [ "$deadcode_count" -gt 10 ]; then
    echo "❌ Too much dead code: $deadcode_count items"
    exit 1
fi

echo "✅ Code quality checks passed"

Demo Project

A comprehensive example project demonstrating all CodeSearch capabilities is available in the examples/demo-project/ directory.

Run the demo:

cd examples/demo-project
./demo.sh

Demo includes:

• Multi-language codebase (Rust, Python, TypeScript)
• Intentional code quality issues for detection
• All analysis types demonstrated
• Real-world usage examples

Architecture & Quality

Code Quality Standards

• ✅ 100% test pass rate (173 unit + 36 integration + 23 MCP = 232 tests)
• ✅ Zero clippy warnings (clean code)
• ✅ Modular architecture (40+ focused modules)
• ✅ Thread-safe parallel processing with rayon
• ✅ Comprehensive error handling with custom error types
• ✅ Trait abstractions for extensibility and testability

Performance

• Fast: 3-50ms for typical searches (< 1000 files)
• Parallel: Auto-scales to available CPU cores
• Smart caching: 70-90% cache hit rate for repeated searches
• Memory efficient: Streaming file reading, < 100MB for 10K files

Supported Languages

Native Parsers (High Performance):

• Rust - Full AST parsing with zero-allocation tokenizer
• Python - Complete syntax support including async/await
• JavaScript/TypeScript - ES6+, JSX, TSX support
• Go - Structs, interfaces, methods with receivers
• Java - Classes, interfaces, enums, annotations

48+ Additional Languages via regex patterns including: C/C++, Ruby, PHP, Swift, Kotlin, C#, Haskell, Elixir, Erlang, Scala, Lua, Perl, Shell, SQL, YAML, TOML, JSON, and more.

See codesearch languages for the complete list.

Additional Resources

• Demo Project - Hands-on examples
• DEMO_GUIDE.md - Comprehensive usage guide
• ARCHITECTURE.md - Technical details and design
• SPEC.md - Technical specification
• CLAUDE.md - Contributor guide

License

Apache-2.0 License

Built with Rust • Fast • Precise • 48+ Languages
Version: 0.1.8