Insight — Code Analysis & Exploration CLI

How It Works

flowchart LR
    A["Target Codebase"] --> B["File Discovery & .insightignore"]
    B --> C["AST & Static Metrics Engine"]
    C --> D["Google Gemini Explainer"]
    D --> E["report/ Folder"]
    E --> F["Per-file .md Reports"]
    E --> G["summary.md Overview"]

1. Discovery: Scans your project directory while strictly respecting .insightignore and standard exclusions (node_modules, venv, .git).
2. Static Analysis: Extracts line counts, functions, classes, imports, and comment density.
3. AI Explainer: Leverages Google's Gemini API to summarize file responsibilities, core workflows, and architectural roles.
4. Structured Reports: Produces a clean Markdown report suite inside a dedicated report/ folder.

Key Features

• Broad Language Support: Detects and processes 35+ file types across systems, backends, frontends, and config files.
• Static Metrics Collection: Accurately tallies total lines, comments, functions, classes, and imported dependencies.
• AI-Powered File Walkthroughs: Explains intricate functions, algorithms, and business logic in plain, accessible language.
• Actionable Markdown Output: Generates clean, navigable .md reports ready to commit into documentation centers or wikis.
• Lightweight CLI: Zero heavy background daemons or database setup required.

Quick Start

1. Install via pip

Install the published package directly from PyPI:

pip install insight-cli-sarang

2. Set Your API Key

Get a free API key from Google AI Studio and set it in your environment:

# macOS / Linux (Bash or Zsh):
export GOOGLE_API_KEY="your_api_key_here"

# Windows (PowerShell):
$env:GOOGLE_API_KEY="your_api_key_here"

# Windows (Command Prompt):
set GOOGLE_API_KEY=your_api_key_here

(Note: GEMINI_API_KEY is also supported as an alias).

3. Run Analysis

Analyze your current project directory:

insight .
# or
insight-cli .

View the generated reports:

ls report/
cat report/summary.md

CLI Reference & Examples

usage: insight [-h] [--version] [-o OUTPUT] [--limit LIMIT] path

Common Examples

# Analyze a specific repository folder
insight /path/to/my-codebase

# Save reports to a custom folder
insight . -o ./docs/codebase_audit

# Test run on only the first 5 source files
insight . --limit 5

Supported File Types

Insight parses and categorizes files across major development domains:

Output Report Structure

When Insight completes, your output folder is organized as follows:

report/
├── summary.md              # Global repository summary and file index
├── cli.py.md               # Explanation & metrics for cli.py
├── analyzer.py.md          # Explanation & metrics for analyzer.py
└── ...

Sample summary.md:

# Insight Codebase Summary

**Total files analyzed:** 14
**Total lines of code:** 2,480

## Files Included
- [cli.py](cli.py.md) (120 lines)
- [analyzer.py](analyzer.py.md) (245 lines)

Roadmap & Upcoming Features

• Offline / Static-Only Mode: Run without an API key using --static (#30)
• Tree-Sitter Multi-Language AST: Real function, class, and export extraction for JS/TS, Go, Rust, and Java (#32)
• Concurrent Processing: Async multi-threaded file analysis with rate limit backoff (#33)
• Local LLM Support: Offline AI summaries via Ollama and LM Studio (#31)
• Interactive HTML Dashboard: Standalone responsive single-page report (#34)

Documentation

For in-depth guides, visit:

• INSTRUCTION.md: Complete setup, API keys, environment persistence, and troubleshooting FAQs.
• CONTRIBUTING.md: Contributor guidelines, development environment setup, coding standards, and PR workflows.
• CODE_OF_CONDUCT.md: Community participation standards.

Contributing

Contributions are warmly welcomed! Please check out open issues or look for good first issue tags to get started.

git clone https://github.com/ferrix-lab/Insight-Py.git
cd Insight-Py
pip install -e ".[dev]"
pytest

License

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