Metadata-Version: 2.4
Name: reveal-cli
Version: 0.13.3
Summary: Semantic code exploration with progressive disclosure - explore directories, files, and code elements with smart defaults
Author-email: Progressive Reveal Contributors <scottsen@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/scottsen/reveal
Project-URL: Repository, https://github.com/scottsen/reveal
Project-URL: Documentation, https://github.com/scottsen/reveal/tree/main/docs
Project-URL: Bug Tracker, https://github.com/scottsen/reveal/issues
Project-URL: Discussions, https://github.com/scottsen/reveal/discussions
Project-URL: Changelog, https://github.com/scottsen/reveal/releases
Keywords: cli,file-explorer,ai,agentic,progressive-disclosure,code-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tree-sitter==0.21.3
Requires-Dist: tree-sitter-languages>=1.10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: treesitter
Provides-Extra: excel
Requires-Dist: openpyxl>=3.0; extra == "excel"
Provides-Extra: syntax
Requires-Dist: pygments>=2.0; extra == "syntax"
Dynamic: license-file

# reveal - Explore Code Semantically

> **The simplest way to understand code**
>
> Point it at a directory, file, or function. Get exactly what you need with zero configuration.

## 🎯 The Problem

Developers and AI agents waste time reading entire files when they only need to understand structure or extract specific functions. There's no standard way to progressively explore code.

## 💡 The Solution

`reveal` provides smart, semantic exploration of codebases:
- **Directories** → See what's inside
- **Files** → See structure (imports, functions, classes)
- **Elements** → See implementation (extract specific function/class)

All with perfect `filename:line` integration for vim, git, grep, and other tools.

---

## Part of the Semantic Infrastructure Lab

**reveal** is a production component of the [Semantic Infrastructure Lab (SIL)](https://github.com/semantic-infrastructure-lab/sil) — building the semantic substrate for intelligent systems.

**Role in the Semantic OS:**
- **Layer 5:** Human Interfaces / SIM (progressive disclosure of structure)

**SIL Principles Applied:**
- ✅ **Clarity** — Explicit structure visibility (no hidden complexity)
- ✅ **Simplicity** — Zero configuration, smart defaults
- ✅ **Composability** — Unix tool composition (pipes, grep, vim)
- ✅ **Correctness** — Reliable parsing via Tree-sitter
- ✅ **Verifiability** — Precise line numbers, reproducible output

**Quick Links:** [SIL Manifesto](https://github.com/semantic-infrastructure-lab/sil/blob/main/docs/canonical/MANIFESTO.md) • [Unified Architecture](https://github.com/semantic-infrastructure-lab/sil/blob/main/docs/architecture/UNIFIED_ARCHITECTURE_GUIDE.md) • [Project Index](https://github.com/semantic-infrastructure-lab/sil/blob/main/projects/PROJECT_INDEX.md)

---

## ⚡ Quick Start

**Install:**
```bash
pip install reveal-cli
```

Includes full support for 18 file types out of the box (Python, JavaScript, TypeScript, Rust, Go, and more).

**Use:**
```bash
reveal src/                    # Directory → tree view
reveal app.py                  # File → structure
reveal app.py load_config      # Element → extraction
```

**That's it.** No flags, no configuration, just works.

## 🔍 Pattern Detection (v0.13.0+)

Industry-aligned code quality checking with pluggable rules:

```bash
# Check code quality
reveal app.py --check

# Select specific categories (B=bugs, S=security, C=complexity, E=errors)
reveal app.py --check --select B,S

# Ignore specific rules
reveal app.py --check --ignore E501

# List all available rules
reveal --rules

# Explain a specific rule
reveal --explain B001
```

**Built-in Rules:**
- **B001**: Bare except clauses (Python)
- **S701**: Docker :latest tags (Dockerfile)
- **C901**: Function complexity (Universal)
- **E501**: Line length (Universal)
- **U501**: Insecure HTTP URLs (Universal)

**Extensible:** Drop custom rules in `~/.reveal/rules/` - auto-discovered, zero configuration!

## 🤖 AI Agent Support (v0.13.0+)

Built-in comprehensive usage guide for AI agents and LLMs:

```bash
# Get strategic guidance for AI agents
reveal --agent-help
```

**Includes:**
- **Decision trees** - When to use reveal vs alternatives
- **Workflow sequences** - Common task patterns (PR review, bug investigation, etc.)
- **Token efficiency analysis** - Cost comparisons for different approaches
- **Anti-patterns** - What NOT to do
- **Pipeline composition** - Combining with git, find, jq, etc.

**Following the `llms.txt` pattern:** Just as websites provide `llms.txt` to guide AI agents, reveal provides `--agent-help` to show CLI tools how to be used effectively by agents.

## 🎨 Clean Design

### Smart Auto-Detection

```bash
# Directories → tree view
$ reveal src/
📁 src/
├── app.py (247 lines, Python)
├── database.py (189 lines, Python)
└── models/
    ├── user.py (156 lines, Python)
    └── post.py (203 lines, Python)

# Files → structure view
$ reveal app.py
📄 app.py

Imports (3):
  app.py:1    import os, sys
  app.py:2    from typing import Dict

Functions (5):
  app.py:15   load_config(path: str) -> Dict
  app.py:28   setup_logging(level: str) -> None

Classes (2):
  app.py:95   Database
  app.py:145  RequestHandler

# Elements → extraction
$ reveal app.py load_config
app.py:15-27 | load_config

   15  def load_config(path: str) -> Dict:
   16      """Load configuration from JSON file."""
   17
   18      if not os.path.exists(path):
   19          raise FileNotFoundError(f"Config not found: {path}")
   20
   21      with open(path) as f:
   22          return json.load(f)
```

### Perfect Unix Integration

Every line is `filename:line` format:

```bash
# Works with vim
$ reveal app.py | grep "Database"
  app.py:95     Database

$ vim app.py:95

# Works with git
$ reveal app.py | grep "load_config"
  app.py:15   load_config(path: str) -> Dict

$ git blame app.py -L 15,27

# Pipe to other tools
$ reveal app.py --format=grep | grep "config"
app.py:15:def load_config(path: str) -> Dict:
app.py:18:    if not os.path.exists(path):
```

## 🔌 Adding New File Types (Stupidly Easy)

### Tree-Sitter Languages (10 lines!)

```python
from reveal import TreeSitterAnalyzer, register

@register('.go', name='Go', icon='🔷')
class GoAnalyzer(TreeSitterAnalyzer):
    language = 'go'
```

**Done!** Full Go support with structure extraction and element access.

Works for: Python, Rust, Go, JavaScript, TypeScript, C#, Java, PHP, Bash, C, C++, Swift, Kotlin, and 40+ more languages!

### Custom Analyzers (20-50 lines)

```python
from reveal import FileAnalyzer, register

@register('.md', name='Markdown', icon='📝')
class MarkdownAnalyzer(FileAnalyzer):
    def get_structure(self):
        """Extract headings."""
        headings = []
        for i, line in enumerate(self.lines, 1):
            if line.startswith('#'):
                headings.append({'line': i, 'name': line.strip('# ')})
        return {'headings': headings}

    def extract_element(self, element_type, name):
        """Extract a section."""
        # Custom extraction logic
        ...
```

That's it! Your file type now works with reveal.

## 🚀 Features

- ✅ **URI adapters** - Explore ANY resource via URIs: `env://`, with more coming soon! (NEW in v0.11.0!)
- ✅ **Hierarchical outline mode** - `--outline` shows code structure as a tree (v0.9.0)
- ✅ **Smart defaults** - No flags needed for 99% of use cases
- ✅ **Directory trees** - See what's in a folder
- ✅ **Structure extraction** - Imports, functions, classes, signals (GDScript)
- ✅ **Element extraction** - Get specific function/class
- ✅ **Pattern detection** - `--check` flag finds code quality issues (v0.13.0)
- ✅ **18 file types built-in** - Python, Rust, Go, JavaScript, TypeScript, GDScript, Bash, Jupyter, Markdown, JSON, YAML, TOML, Nginx, Dockerfile, and more
- ✅ **Shebang detection** - Extensionless scripts work automatically (detects `#!/usr/bin/env python3`, `#!/bin/bash`)
- ✅ **50+ languages available** - Via optional tree-sitter (JS, TS, C#, Java, PHP, etc.)
- ✅ **Perfect line numbers** - `filename:line` format everywhere
- ✅ **Unix composable** - Works with vim, git, grep, sed, awk
- ✅ **Multiple output formats** - text (default), json, grep
- ✅ **Easy to extend** - Add new file type in 10-50 lines
- ✅ **AI-optimized** - Designed for agentic workflows
- ✅ **Windows compatible** - Full UTF-8/emoji support

## 📚 Real-World Examples

### Hierarchical Outline (NEW!)
```bash
# See code structure as a tree
$ reveal app.py --outline
UserManager (app.py:1)
  ├─ create_user(self, username) [3 lines, depth:0] (line 4)
  ├─ delete_user(self, user_id) [3 lines, depth:0] (line 8)
  └─ UserValidator (nested class, line 12)
     └─ validate_email(self, email) [2 lines, depth:0] (line 15)

# Find complex code with outline view
$ reveal app.py --outline --check
```

### AI Agent Workflow
```bash
# Start broad
$ reveal src/
# Pick interesting file
$ reveal src/app.py
# Deep dive
$ reveal src/app.py Database
```

### Developer Quick Lookup
```bash
# See function implementation
$ reveal app.py load_config

# Jump to edit
$ vim app.py:15
```

### Game Development (GDScript)
```bash
# Explore Godot scripts
$ reveal player.gd
📄 player.gd

Functions (4):
  player.gd:11    _ready() -> void
  player.gd:16    take_damage(amount: int) -> void
  player.gd:24    die() -> void

Signals (2):
  player.gd:3     health_changed(new_health)
  player.gd:4     died()

# Extract specific function
$ reveal player.gd take_damage
player.gd:16-23 | take_damage

   16  func take_damage(amount: int) -> void:
   17      """Reduce health by amount."""
   18      current_health -= amount
   19      emit_signal("health_changed", current_health)
```

### Integration with Tools
```bash
# Find all TODO comments
$ reveal src/*.py | grep -i "todo"

# Count functions per file
$ for f in src/*.py; do echo "$f: $(reveal $f | grep -c 'Functions')"; done

# Extract all function names
$ reveal app.py | awk '/Functions/,/^$/ {if ($2 ~ /:/) print $3}'
```

### Unix Pipeline Workflows (--stdin)
```bash
# Analyze files from find
$ find src/ -name "*.py" | reveal --stdin --check

# Analyze changed files in git
$ git diff --name-only | reveal --stdin --outline

# Combine with jq for powerful filtering
$ find . -name "*.py" | \
  reveal --stdin --format=json | \
  jq '.functions[] | select(.line_count > 100)'

# CI/CD: Check for code quality issues in PR
$ git diff --name-only origin/main | \
  grep "\.py$" | \
  reveal --stdin --check --format=grep
```

The `--stdin` flag enables composability with any tool that outputs file paths:
- `find` - Complex file discovery
- `git` - Changed files, file lists
- `ls` - Simple file lists
- `grep -l` - Files matching patterns
- Custom scripts - Dynamic file selection

### 🌐 URI Adapters - Explore ANY Resource! (NEW in v0.11!)

reveal isn't just for files anymore. Use URIs to explore any structured resource:

```bash
# Environment variables
$ reveal env://
Environment Variables (82)

System (9):
  HOME                           /home/user
  PATH                           /usr/local/bin:/usr/bin
  SHELL                          /bin/bash
  ...

Python (2):
  PYTHONPATH                     /app:/app/lib
  VIRTUAL_ENV                    /app/venv

# Get specific variable
$ reveal env://DATABASE_URL
Environment Variable: DATABASE_URL
Category: Application
Value: postgresql://localhost/mydb
Length: 29 characters

# JSON output for scripting
$ reveal env:// --format=json | jq '.categories.Python'
[
  {
    "name": "PYTHONPATH",
    "value": "/app:/app/lib",
    "sensitive": false,
    "length": 13
  }
]

# Find sensitive variables
$ reveal env:// | grep "(sensitive)"
  API_KEY                        *** (sensitive)
  DATABASE_PASSWORD              *** (sensitive)
```

**Why use URI adapters?**
- **Consistent interface** - Same reveal UX for any resource
- **Progressive disclosure** - Overview → specific element
- **Multiple formats** - text, json, grep (just like files)
- **Composable** - Works with jq, grep, and other tools

**Coming soon:** `https://` (REST APIs), `git://` (repositories), `docker://` (containers), and more!

## 🎯 Use Cases

**For AI Agents:**
- Explore unknown codebases efficiently
- Get structure without reading full files
- Extract specific elements on demand
- Standard interface across all file types

**For Developers:**
- Quick reference without opening editor
- Understand file structure rapidly
- Find specific functions/classes
- Perfect for terminal workflows

**For Scripts:**
- JSON output for programmatic access
- Grep-compatible format
- Composable with Unix tools
- Reliable filename:line references

## 🏗️ Architecture

```
reveal/
├── base.py              # Registration & analyzer base (~380 lines)
├── main.py              # CLI & output formatting (~920 lines)
├── treesitter.py        # TreeSitter integration for 50+ languages (~345 lines)
├── tree_view.py         # Directory tree rendering (~105 lines)
├── analyzers/           # File type analyzers
│   ├── python.py        # 15 lines (tree-sitter)
│   ├── rust.py          # 13 lines (tree-sitter)
│   ├── nginx.py         # 186 lines (custom logic)
│   ├── markdown.py      # 312 lines (custom logic)
│   └── ...              # 14 analyzers total
└── adapters/            # URI adapters (NEW!)
    ├── base.py          # Adapter protocol
    ├── env.py           # Environment variables (v0.11.0)
    └── ...              # More coming! (postgres, docker, https)
```

**Total codebase:** ~3,400 lines
**Core:** ~1,700 lines
**Analyzers:** 10-300 lines each (most are < 25 lines!)
**Adapters:** New system for exploring non-file resources

**See:** [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for deep dive

## 📖 Optional Flags

```bash
# Discovery
reveal --version              # Show version
reveal --list-supported       # List all supported file types

# Metadata only
reveal app.py --meta

# JSON output
reveal app.py --format=json

# Grep-compatible output
reveal app.py --format=grep

# Directory depth
reveal src/ --depth=5
```

## 🤝 Contributing

We welcome contributions! Adding a new file type takes 10-50 lines of code.

**Most wanted:**
- New language analyzers (TypeScript, Java, Swift, Kotlin)
- Better extraction logic for existing analyzers
- Documentation improvements
- Bug reports and feature requests

## 📜 License

MIT License - See [LICENSE](LICENSE)

## 🔗 Links

- **GitHub:** https://github.com/scottsen/reveal
- **Issues:** https://github.com/scottsen/reveal/issues
- **Discussions:** https://github.com/scottsen/reveal/discussions

## 🌟 Vision

Make `reveal` the standard way to explore code - for humans and AI agents alike. Clean, simple, powerful.

---

**Status:** 🚀 v0.13.3 - Windows Compatibility | **License:** MIT | **Roadmap:** [ROADMAP.md](ROADMAP.md)

[![GitHub Stars](https://img.shields.io/github/stars/scottsen/reveal?style=social)](https://github.com/scottsen/reveal)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
