project-examer 0.2.1

A fast system analysis tool for scanning codebases and building intelligent relationships between files using AST parsing and LLM analysis
Documentation

Project Examer 🔍

A fast, comprehensive system analysis tool for scanning directories and building intelligent relationships between files using AST parsing and LLM analysis.

Features

  • 🚀 Fast File Discovery: Recursive directory scanning with configurable ignore patterns
  • 🌳 AST Parsing: Support for multiple languages using Tree-sitter
  • 🕸️ Dependency Graph: Build comprehensive dependency relationships
  • 🤖 LLM Analysis: AI-powered insights using OpenAI, Anthropic, or local Ollama
  • 📊 Rich Reporting: Generate HTML, JSON, and Markdown reports
  • ⚡ Parallel Processing: Efficient multi-threaded file processing
  • 🔧 Configurable: Fully customizable via TOML configuration

Supported Languages

  • TypeScript/JavaScript (with JSX/TSX)
  • Python
  • Rust
  • Java
  • Go
  • C/C++
  • And more...

Installation

From Source

git clone <repository-url>
cd project-examer
cargo install --path .

Global Installation

# Install from crates.io
cargo install project-examer

After global installation, the tool is available as project-examer from anywhere.

Quick Start

Analyze a project

# Analyze current directory
project-examer analyze

# Analyze specific directory
project-examer analyze --path /path/to/project

# Skip LLM analysis for faster local-only results
project-examer analyze --skip-llm

# Use custom configuration
project-examer analyze --config custom-config.toml

Generate configuration file

# Generate config at default location (~/.project-examer.toml)
project-examer config

# Generate config at custom location
project-examer config --output my-config.toml

Configuration

Project Examer looks for configuration in the following order:

  1. Custom path specified with --config
  2. ~/.project-examer.toml (user's home directory)
  3. Built-in defaults

Generate a configuration file with all options documented:

project-examer config  # Creates ~/.project-examer.toml with full documentation

Environment Variables

API keys can be provided via environment variables:

  • OPENAI_API_KEY - for OpenAI GPT models
  • ANTHROPIC_API_KEY - for Claude models

Configuration File Structure

target_directory = "."
ignore_patterns = ["node_modules", ".git", "target", "build", "dist"]
file_extensions = ["rs", "js", "ts", "tsx", "jsx", "py", "java", "go"]
max_file_size = 1048576  # 1MB

[llm]
provider = "OpenAI"  # Options: "OpenAI", "Ollama", "Anthropic"
model = "gpt-4"
max_tokens = 4000
temperature = 0.1
# api_key = "your-key"  # Or use environment variables

[analysis]
include_dependencies = true
include_function_calls = true
include_architecture_patterns = true
include_security_analysis = false
max_depth = 10

Output

Project Examer generates comprehensive analysis reports:

📄 Analysis Report (HTML/JSON/Markdown)

  • Executive summary with complexity and maintainability scores
  • File analysis with language breakdown
  • Dependency graph metrics
  • LLM-generated insights and recommendations

🔍 Key Insights

  • Architecture patterns detected
  • Code quality assessment
  • Security vulnerabilities (when enabled)
  • Refactoring opportunities
  • Documentation gaps

Examples

You'll find examples of what reports are produced in the ./example-output/ directory.

Analyze a React project

project-examer analyze --path ./my-react-app --output ./analysis-results

First Time Setup

# Create configuration file with all options documented
project-examer config

# Edit the configuration file
vim ~/.project-examer.toml  # On Unix-like systems
notepad %USERPROFILE%\.project-examer.toml  # On Windows

# Set your API key (or use environment variable)
export OPENAI_API_KEY="your-openai-api-key"

Analyze with custom LLM settings

# Using Ollama locally
project-examer config --output ollama-config.toml
# Edit ollama-config.toml to set provider="Ollama", base_url="http://localhost:11434"
project-examer analyze --config ollama-config.toml

Local-only analysis (no API calls)

project-examer analyze --skip-llm

Architecture

  • File Discovery: Uses ignore crate for efficient file traversal
  • AST Parsing: Tree-sitter for robust language parsing
  • Dependency Graph: Petgraph for relationship modeling
  • Parallel Processing: Rayon for multi-threaded file processing
  • LLM Integration: Supports multiple providers with rate limiting

Development

# Build
cargo build

# Run tests
cargo test

# Run with debug output
RUST_LOG=debug cargo run -- analyze --path ./test-project

# Build release version
cargo build --release

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Submit a pull request

Use Cases

  • Code Reviews: Understand codebase architecture before reviewing
  • Documentation: Generate architectural documentation automatically
  • Refactoring: Identify code smells and improvement opportunities
  • Security Audits: Detect potential security vulnerabilities
  • Onboarding: Help new team members understand project structure

Performance

  • Processes ~1000 files per second (varies by file size and complexity)
  • Memory efficient with streaming file processing
  • Parallel parsing for optimal CPU utilization
  • Configurable rate limiting for LLM API calls

License

MIT License - see LICENSE file for details.

Project Examer - Making codebase analysis fast, comprehensive, and intelligent. 🚀