📚 Navix Documentation

Complete documentation for the Navix file navigator and symbol indexing tool

Table of Contents

  1. Overview
  2. Architecture
  3. Installation
  4. Usage Guide
  5. API Reference
  6. Development Guide
  7. Troubleshooting
  8. Examples
  9. Contributing

Overview

Navix is a lightning-fast C++ file navigator with symbol indexing and autocomplete capabilities. It provides a powerful TUI (Text User Interface) for navigating codebases and finding symbols across multiple programming languages.

Key Features

Supported Languages

Language File Extensions Symbol Types
C++ .cpp, .hpp, .cc, .hh, .cxx, .hxx Functions, Classes, Structs, Variables, Enums, Typedefs, Macros, Namespaces
TypeScript/JavaScript .ts, .js, .tsx, .jsx Functions, Classes, Interfaces, Types, Constants, Imports, Exports
Python .py, .pyw Functions, Classes, Methods, Variables, Imports, Decorators
Go .go Functions, Methods, Structs, Interfaces, Types, Variables, Constants
Swift .swift Functions, Methods, Classes, Structs, Protocols, Enums, Extensions
Kotlin .kt, .kts Functions, Classes, Objects, Variables, Properties
Java .java Methods, Classes, Interfaces, Variables, Constants
PHP .php Functions, Classes, Variables, Constants
Ruby .rb Methods, Classes, Modules, Variables, Constants
Rust .rs Functions, Structs, Enums, Traits, Variables
Bash/Shell .sh, .bash Functions, Variables, Aliases
Text .txt, .md, .rst Headers, URLs, Emails, TODOs, Notes

Architecture

Core Components

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   FileScanner   │    │   SymbolIndex   │    │   TUI Engine    │
│                 │    │                 │    │                 │
│ • Scan files    │───▶│ • Parse symbols │───▶│ • Interactive   │
│ • Filter types  │    │ • Build index   │    │   interface     │
│ • Recursive     │    │ • Search        │    │ • Navigation    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  FileWatcher    │    │ Autocomplete    │    │ Performance     │
│                 │    │   Engine        │    │   Logger        │
│ • Watch changes │    │ • Fuzzy match   │    │ • Profile ops   │
│ • Real-time     │    │ • Prefix match  │    │ • Metrics       │
│ • Notifications │    │ • Suggestions   │    │ • Reports       │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Class Hierarchy

Core Classes

  1. SymbolIndex - Main symbol parsing and indexing engine
  2. FileScanner - File system scanning and filtering
  3. TUI - Text User Interface for interactive navigation
  4. FileWatcher - Real-time file system monitoring
  5. AutocompleteEngine - Intelligent code completion
  6. PerformanceLogger - Performance profiling and metrics
  7. JsonExporter - Export symbols to various formats
  8. LSPServer - Language Server Protocol implementation

Symbol Types

enum class SymbolType {
    // C++ symbols
    FUNCTION, CLASS, STRUCT, VARIABLE, ENUM, TYPEDEF, MACRO, NAMESPACE,

    // TypeScript/JavaScript symbols
    JS_FUNCTION, JS_ARROW_FUNCTION, JS_CLASS, JS_INTERFACE, JS_TYPE,
    JS_CONST, JS_LET, JS_VAR, JS_IMPORT, JS_EXPORT, JS_MODULE,

    // Python symbols
    PY_FUNCTION, PY_CLASS, PY_METHOD, PY_VARIABLE, PY_IMPORT,
    PY_FROM_IMPORT, PY_DECORATOR, PY_LAMBDA,

    // Go symbols
    GO_FUNCTION, GO_METHOD, GO_STRUCT, GO_INTERFACE, GO_TYPE,
    GO_VARIABLE, GO_CONSTANT, GO_PACKAGE, GO_IMPORT,

    // Swift symbols
    SWIFT_FUNCTION, SWIFT_METHOD, SWIFT_CLASS, SWIFT_STRUCT,
    SWIFT_PROTOCOL, SWIFT_ENUM, SWIFT_EXTENSION, SWIFT_VARIABLE,
    SWIFT_CONSTANT, SWIFT_PROPERTY, SWIFT_INITIALIZER, SWIFT_SUBSCRIPT,
    SWIFT_IMPORT,

    // Text file symbols
    TXT_HEADER, TXT_SUBHEADER, TXT_URL, TXT_EMAIL, TXT_TODO,
    TXT_NOTE, TXT_FIXME, TXT_LINE, TXT_WORD,

    UNKNOWN
};

Platform Support

Unix/Linux/macOS

Windows

Installation

Prerequisites

Platform-Specific Dependencies

Unix/Linux/macOS

# Ubuntu/Debian
sudo apt install libncurses5-dev pkg-config

# Fedora/RHEL
sudo dnf install ncurses-devel pkg-config

# macOS
brew install ncurses pkg-config

Windows

Installation Methods

1. Package Managers

Linux (Debian/Ubuntu)

# Build and install .deb package
./build_deb.sh
sudo dpkg -i navix_1.0.0_amd64.deb

macOS

# Build and install .pkg
./build.sh pkg
sudo installer -pkg navix-installer.pkg -target /

2. Manual Build

# Clone repository
git clone https://github.com/zidniryi/navix.git
cd navix

# Build for current platform
./build.sh native

# Build for all platforms
./build.sh all

# Build for Windows (cross-compilation)
./build.sh windows

3. CMake Build

mkdir build && cd build
cmake ..
make

Verification

# Check installation
navix --version

# Test basic functionality
navix . --search main

Usage Guide

Basic Commands

1. Scan Project

# Scan all supported files in current directory
navix .

# Scan specific directory
navix /path/to/project

# Scan with specific file types
navix . --cpp          # C++ files only
navix . --ts           # TypeScript/JavaScript files
navix . --py           # Python files only

2. Search Symbols

# Search for symbols (fuzzy matching)
navix . --search functionName

# Exact search
navix . --search "exactSymbolName"

# Navigate to specific symbol
navix . --goto className

3. Interactive Modes

# Interactive TUI mode
navix . --tui

# Interactive autocomplete
navix . --autocomplete

# Get completions for query
navix . --complete "partialName"

4. Live Monitoring

# Live file watching
navix . --live

# Live mode with performance logging
navix . --live --perf

5. Export Formats

# Export to JSON
navix . --json symbols.json

# Export compact JSON
navix . --json-compact

# Export with statistics
navix . --json-stats

# Export LSP-compatible JSON
navix . --json-lsp

# Export ctags format
navix . --export-tags

Advanced Usage

Performance Monitoring

# Enable performance logging
navix . --perf

# View performance metrics
navix . --perf --json-stats

Language Server Protocol

# Start LSP server mode
navix . --lsp

Custom File Extensions

# Scan specific file extensions
navix . --ext .cpp .hpp .cc .hh

Interactive TUI Commands

When in TUI mode (--tui), use these keyboard shortcuts:

Key Action
j/k Navigate up/down
Enter Open file at symbol
Ctrl+f Search mode
Ctrl+n Next search result
Ctrl+p Previous search result
q Quit
h Help
Ctrl+c Force quit

API Reference

SymbolIndex Class

Constructor

SymbolIndex();

Public Methods

void addSymbol(const Symbol& symbol)

Add a symbol to the index.

Parameters:

Example:

SymbolIndex index;
Symbol sym("main", SymbolType::FUNCTION, "main.cpp", 10);
index.addSymbol(sym);
void buildIndex(const std::vector<std::string>& files)

Build symbol index from a list of files.

Parameters:

Example:

std::vector<std::string> files = {"main.cpp", "utils.hpp"};
index.buildIndex(files);
std::vector<Symbol> search(const std::string& query, bool fuzzy = true)

Search for symbols using fuzzy or exact matching.

Parameters:

Returns:

Example:

auto results = index.search("main", true);
for (const auto& symbol : results) {
    std::cout << symbol.name << " in " << symbol.file << ":" << symbol.line << "\n";
}
std::vector<Symbol> exactSearch(const std::string& query)

Perform exact symbol search.

Parameters:

Returns:

std::vector<Symbol> fuzzySearch(const std::string& query)

Perform fuzzy symbol search using Levenshtein distance.

Parameters:

Returns:

void clear()

Clear all symbols from the index.

size_t size() const

Get the number of symbols in the index.

Returns:

std::string symbolTypeToString(SymbolType type) const

Convert symbol type enum to string representation.

Parameters:

Returns:

FileScanner Class

Static Methods

std::vector<std::string> scanDirectory(const std::string& rootPath)

Scan directory for all supported file types.

Parameters:

Returns:

Example:

auto files = FileScanner::scanDirectory("/path/to/project");
std::vector<std::string> scanByExtensions(const std::string& rootPath, const std::vector<std::string>& extensions)

Scan directory for specific file extensions.

Parameters:

Returns:

Example:

std::vector<std::string> exts = {".cpp", ".hpp"};
auto files = FileScanner::scanByExtensions("/path/to/project", exts);

TUI Class

Constructor

TUI(SymbolIndex& index);

Public Methods

void run()

Start the interactive TUI interface.

Example:

SymbolIndex index;
TUI tui(index);
tui.run();
void setSearchQuery(const std::string& query)

Set the initial search query.

Parameters:

FileWatcher Class

Constructor

FileWatcher(const std::string& path);

Public Methods

void start()

Start watching for file changes.

void stop()

Stop file watching.

void setCallback(std::function<void(const std::string&)> callback)

Set callback function for file change events.

Parameters:

Example:

FileWatcher watcher("/path/to/project");
watcher.setCallback([](const std::string& file) {
    std::cout << "File changed: " << file << "\n";
});
watcher.start();

AutocompleteEngine Class

Constructor

AutocompleteEngine(const SymbolIndex& index);

Public Methods

std::vector<std::string> getCompletions(const std::string& query)

Get autocomplete suggestions for a query.

Parameters:

Returns:

Example:

AutocompleteEngine engine(index);
auto completions = engine.getCompletions("main");

PerformanceLogger Class

Constructor

PerformanceLogger();

Public Methods

void startTimer(const std::string& operation)

Start timing an operation.

Parameters:

void endTimer(const std::string& operation)

End timing an operation.

Parameters:

void logMetric(const std::string& metric, double value)

Log a performance metric.

Parameters:

std::string getReport() const

Get performance report as string.

Returns:

JsonExporter Class

Static Methods

void exportToJson(const SymbolIndex& index, const std::string& filename, bool compact = false)

Export symbols to JSON file.

Parameters:

Example:

JsonExporter::exportToJson(index, "symbols.json", false);
void exportToCtags(const SymbolIndex& index, const std::string& filename)

Export symbols to ctags format.

Parameters:

Development Guide

Building from Source

Prerequisites

# Install build dependencies
# Ubuntu/Debian
sudo apt install build-essential cmake libncurses5-dev pkg-config

# macOS
brew install cmake ncurses pkg-config

# Windows
# Install Visual Studio or MinGW-w64

Build Process

# Clone repository
git clone https://github.com/zidniryi/navix.git
cd navix

# Create build directory
mkdir build && cd build

# Configure with CMake
cmake -DCMAKE_BUILD_TYPE=Release ..

# Build
make -j$(nproc)

# Install (optional)
sudo make install

Development Build

# Configure with debug symbols
cmake -DCMAKE_BUILD_TYPE=Debug ..

# Build with debug information
make -j$(nproc)

# Run with debugging
gdb ./navix

Adding Language Support

Step 1: Define Symbol Types

Add new symbol types to SymbolType enum in src/Symbol.hpp:

enum class SymbolType {
    // ... existing types ...

    // New language symbols
    NEW_FUNCTION,
    NEW_CLASS,
    NEW_VARIABLE,
    // ...
};

Step 2: Add File Detection

Implement file detection method in SymbolIndex class:

bool SymbolIndex::isNewLanguage(const std::string& filePath) const {
    std::string ext = filePath.substr(filePath.find_last_of('.'));
    return ext == ".new" || ext == ".ext";
}

Step 3: Implement Parser

Add parsing method for the new language:

void SymbolIndex::parseNewLanguage(const std::string& line, 
                                  const std::string& filePath, 
                                  int lineNumber) {
    // Implement language-specific parsing logic
    std::regex functionRegex(R"(\bfunction\s+(\w+))");
    std::smatch match;

    if (std::regex_search(line, match, functionRegex)) {
        addSymbol(Symbol(match[1].str(), SymbolType::NEW_FUNCTION, 
                        filePath, lineNumber, line));
    }

    // Add more patterns as needed
}

Step 4: Update String Conversion

Add string conversion for new symbol types:

std::string SymbolIndex::symbolTypeToString(SymbolType type) const {
    switch (type) {
        // ... existing cases ...
        case SymbolType::NEW_FUNCTION: return "new-function";
        case SymbolType::NEW_CLASS: return "new-class";
        // ...
    }
}

Step 5: Add to File Scanner

Update file scanner to include new extensions:

std::vector<std::string> FileScanner::scanForNewLanguage(const std::string& rootPath) {
    std::vector<std::string> extensions = {".new", ".ext"};
    return scanByExtensions(rootPath, extensions);
}

Step 6: Update CLI Interface

Add command-line option in main.cpp:

} else if (mode == "--newlang") {
    files = FileScanner::scanForNewLanguage(rootPath);
    std::cout << "🔍 Scanning for New Language files in: " << rootPath << "\n";
    // ... output logic
}

Testing

Unit Tests

# Run unit tests (if available)
make test

# Run specific test
./test_symbol_index

Manual Testing

# Test basic functionality
./navix . --search main
./navix . --goto FileScanner
./navix . --export-tags

# Test edge cases
./navix /nonexistent/path
./navix . --search ""
./navix . --goto NonexistentSymbol

# Test different file types
./navix . --cpp
./navix . --ts
./navix . --py

Performance Testing

# Test with large codebase
./navix /path/to/large/project --perf

# Compare performance
time ./navix . --search main

Code Style

C++ Standards

Naming Conventions

// Classes: PascalCase
class SymbolIndex {};

// Functions: camelCase  
void parseFile(const std::string& filePath);

// Variables: camelCase
std::string fileName;

// Constants: UPPER_SNAKE_CASE
const int MAX_SYMBOLS = 1000;

// Private members: trailing underscore
class Example {
private:
    int count_;
};

Code Organization

// Header files (.hpp)
#ifndef FILENAME_HPP
#define FILENAME_HPP

#include <system_headers>
#include "local_headers.hpp"

class Example {
public:
    // Public interface first

private:
    // Private members last
};

#endif // FILENAME_HPP

Troubleshooting

Common Issues

1. Build Errors

Error: ncurses.h: No such file or directory

# Ubuntu/Debian
sudo apt install libncurses5-dev

# macOS
brew install ncurses

# Fedora
sudo dnf install ncurses-devel

Error: pkg-config: command not found

# Ubuntu/Debian
sudo apt install pkg-config

# macOS
brew install pkg-config

2. Runtime Errors

Error: navix: command not found

# Add to PATH
export PATH="/usr/local/bin:$PATH"

# Or create symlink
sudo ln -s /path/to/navix /usr/local/bin/navix

Error: Permission denied

# Make executable
chmod +x navix-native

# Or install properly
sudo make install

3. Performance Issues

Slow symbol indexing

# Use specific file types only
navix . --cpp

# Enable performance logging
navix . --perf

# Check system resources
top
htop

Memory usage high

# Limit file scanning
navix . --ext .cpp .hpp

# Use smaller project subset
navix ./src

4. Platform-Specific Issues

Windows: Console not responding

macOS: ncurses not found

# Install via Homebrew
brew install ncurses

# Set PKG_CONFIG_PATH
export PKG_CONFIG_PATH="/usr/local/opt/ncurses/lib/pkgconfig:$PKG_CONFIG_PATH"

Linux: TUI not displaying correctly

# Check terminal type
echo $TERM

# Set terminal type
export TERM=xterm-256color

# Check ncurses installation
pkg-config --modversion ncurses

Debug Mode

Enable Debug Output

# Build with debug symbols
cmake -DCMAKE_BUILD_TYPE=Debug ..
make

# Run with debug output
./navix . --perf --json-stats

Verbose Mode

# Enable verbose output
./navix . --perf --verbose

# Check all available options
./navix --help

Getting Help

Documentation

Community Support

Examples

Basic Usage Examples

1. Find All Functions

# Find all functions in C++ files
navix . --cpp --search "function"

# Find specific function
navix . --search "main"

# Find functions in specific file
navix . --search "parseFile"

2. Navigate to Classes

# Find all classes
navix . --search "class"

# Navigate to specific class
navix . --goto "SymbolIndex"

# Find classes in specific language
navix . --cpp --search "class"

3. Export Project Structure

# Export to JSON
navix . --json project_symbols.json

# Export compact format
navix . --json-compact compact_symbols.json

# Export with statistics
navix . --json-stats stats_symbols.json

Advanced Examples

1. Multi-Language Project Analysis

# Analyze mixed-language project
navix . --json mixed_languages.json

# Filter by specific languages
navix . --cpp --ts --py --json filtered.json

2. Performance Analysis

# Profile symbol indexing
navix . --perf --json-stats performance.json

# Compare different file types
navix . --cpp --perf
navix . --ts --perf
navix . --py --perf

3. Editor Integration

# Generate ctags for editor
navix . --export-tags .tags

# Start LSP server
navix . --lsp

# Export LSP-compatible format
navix . --json-lsp lsp_symbols.json

4. Live Development

# Watch for changes during development
navix . --live --perf

# Interactive development
navix . --tui

# Autocomplete during coding
navix . --autocomplete

Integration Examples

1. Vim/Neovim Integration

" Add to .vimrc
set tags=.tags
set tags+=./.tags

" Use ctags file generated by Navix
:!navix . --export-tags .tags

2. VS Code Integration

// settings.json
{
    "typescript.preferences.includePackageJsonAutoImports": "on",
    "typescript.suggest.autoImports": true,
    "typescript.preferences.includeCompletionsForModuleExports": true
}

3. Shell Aliases

# Add to .bashrc or .zshrc
alias nav='navix . --tui'
alias navs='navix . --search'
alias navg='navix . --goto'
alias nave='navix . --export-tags'

4. Git Hooks

# .git/hooks/pre-commit
#!/bin/bash
navix . --export-tags .tags
git add .tags

Scripting Examples

1. Batch Processing

#!/bin/bash
# process_projects.sh

for project in /path/to/projects/*; do
    if [ -d "$project" ]; then
        echo "Processing $project"
        navix "$project" --json "$project"_symbols.json
    fi
done

2. CI/CD Integration

# .github/workflows/navix.yml
name: Navix Analysis
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Navix
        run: |
          git clone https://github.com/zidniryi/navix.git
          cd navix
          ./build.sh native
          sudo cp navix-native /usr/local/bin/navix
      - name: Analyze Code
        run: navix . --json-stats analysis.json
      - name: Upload Results
        uses: actions/upload-artifact@v2
        with:
          name: navix-analysis
          path: analysis.json

3. Performance Monitoring

#!/bin/bash
# monitor_performance.sh

echo "Starting Navix performance monitoring..."

# Baseline measurement
start_time=$(date +%s)
navix . --perf --json-stats baseline.json
baseline_time=$(( $(date +%s) - start_time ))

echo "Baseline time: ${baseline_time}s"

# Monitor over time
while true; do
    start_time=$(date +%s)
    navix . --perf --json-stats "perf_$(date +%Y%m%d_%H%M%S).json"
    current_time=$(( $(date +%s) - start_time ))

    echo "$(date): ${current_time}s"

    if [ $current_time -gt $((baseline_time * 2)) ]; then
        echo "WARNING: Performance degradation detected!"
    fi

    sleep 300  # Check every 5 minutes
done

Contributing

Getting Started

  1. Fork the repository
  2. Clone your fork
    git clone https://github.com/your-username/navix.git
cd navix
  3. Create a feature branch
    git checkout -b feature/your-amazing-feature
  4. Make your changes
  5. Test thoroughly
    ./build.sh native
./navix-native . --search test
  6. Commit with clear message
    git commit -m "feat: add amazing new feature"
  7. Push and create pull request

Development Guidelines

Code Style

Testing

Documentation

Areas for Contribution

High Priority

Medium Priority

Nice to Have

Reporting Issues

Before Reporting

When Reporting Include

Recognition

Contributors will be:

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Made with ❤️ for developers who value speed and simplicity.

Navix - Navigate & Index