# Reveal Cool Tricks

> The hidden powers of reveal that will make you a 10x developer

---

## Table of Contents

- [Self-Diagnostic Superpowers](#self-diagnostic-superpowers)
- [AST Query Wizardry](#ast-query-wizardry) (includes Decorator Intelligence NEW v0.23.0)
- [Pipeline Magic](#pipeline-magic)
- [Markdown Surgery](#markdown-surgery)
- [Token Efficiency Mastery](#token-efficiency-mastery)
- [Quality Gatekeeping](#quality-gatekeeping)
- [Discovery Patterns](#discovery-patterns)
- [Format Transformations](#format-transformations)
- [JSON Deep Dive](#json-deep-dive-json-adapter) (json:// adapter)
- [Multi-Language Exploration](#multi-language-exploration)

---

## Self-Diagnostic Superpowers

### Reveal Diagnosing Reveal (The Meta Example)

```bash
# Run from reveal's source directory - watch Python explode
cd ~/src/projects/reveal/external-git/reveal/adapters
reveal env://
# CRASH! types.py shadows Python's stdlib types module

# Now diagnose the problem
cd /tmp
reveal python://module/types
# Output: No conflicts - imports from /usr/lib/python3.10/types.py

reveal python://module/ast
# If you were in reveal's directory, this would detect the conflict
```

**Why this matters:** Reveal's `python://` adapter can detect when YOU'RE running it from a bad location.

### Python Environment Doctor

```bash
# Run automated diagnostics
reveal python://doctor

# Output:
# {
#   "status": "healthy",
#   "health_score": 100,
#   "issues": [],
#   "warnings": [],
#   "recommendations": [],
#   "checks_performed": [
#     "virtual_environment",
#     "cwd_shadowing",
#     "stale_bytecode",
#     "python_version",
#     "editable_installs"
#   ]
# }
```

### Find Stale Bytecode (The Silent Killer)

```bash
# "My code changes aren't working!"
reveal python://debug/bytecode

# Finds .pyc files newer than source = stale bytecode
# Gives you exact cleanup commands:
#   find . -type d -name __pycache__ -exec rm -rf {} +
#   find . -name "*.pyc" -delete
```

### Detect Import Shadowing

```bash
# Is your local module hiding a pip package?
reveal python://module/requests

# Output shows:
# - import_location: Where Python actually imports from
# - pip_package: Where pip thinks it is
# - conflicts: [] or [{ type: "cwd_shadowing", ... }]
# - recommendations: Exact fix if there's a problem
```

### Analyze sys.path Conflicts

```bash
reveal python://syspath

# Shows each path entry with:
# - Priority number (0 = highest)
# - Type: cwd, site-packages, stdlib, pythonpath
# - Warning if CWD shadows packages
```

### Self-Referential Code Extraction (NEW v0.27.0)

**The ultimate meta feature:** Use reveal to extract reveal's own implementation!

```bash
# Extract a specific function from reveal's source
reveal reveal://rules/links/L001.py _extract_anchors_from_markdown

# Extract a class definition
reveal reveal://analyzers/markdown.py MarkdownAnalyzer

# Self-referential extraction - extract the extraction method itself!
reveal reveal://adapters/reveal.py get_element

# Extract adapter help documentation
reveal reveal://adapters/help.py get_help
```

**Why this rocks:**
- Study reveal's implementation without reading full files
- Learn adapter patterns by extracting adapter code
- Perfect for contributors learning the codebase
- Self-documenting architecture - reveal shows you how reveal works

**Pro tip:** Combine with `--format=json` for programmatic analysis:
```bash
reveal reveal://analyzers/markdown.py MarkdownAnalyzer --format=json | jq '.code'
```

---

## AST Query Wizardry

### Complexity Analysis (NEW v0.25.0)

**Tree-sitter based McCabe complexity** - now accurate across all languages!

```bash
# Find complex functions (industry standard: >10 needs refactoring)
reveal 'ast://./src?complexity>10'

# The danger zone - extremely complex functions
reveal 'ast://./src?complexity>20'

# Find functions that are BOTH complex AND long (prime refactoring targets)
reveal 'ast://./src?complexity>15&lines>100'

# Compact but complex - lots of logic in few lines (code golf smell)
reveal 'ast://./src?complexity>10&lines<50'

# Top 10 most complex functions in your codebase
reveal 'ast://./src?type=function' --format=json | \
  jq -r '[.results[] | {name, file, complexity, lines: .line_count}] |
         sort_by(.complexity) | reverse | .[0:10][] |
         "\(.file) - \(.name) (complexity: \(.complexity), lines: \(.lines))"'

# Find all god functions (both metrics high)
reveal 'ast://./src?complexity>30|lines>150'

# Simple but long - candidate for splitting or inlining
reveal 'ast://./src?complexity<5&lines>50'
```

**Real example from reveal's codebase:**
```bash
$ reveal 'ast://reveal?complexity>50'
# Found: _render_typed_structure_output (complexity: 69, 167 lines)
# Found: check/mysql.py (complexity: 58, 154 lines)
# Found: handle_decorator_stats (complexity: 52, 118 lines)
```

### Find Complex Functions

```bash
# Quote the URI! Shell interprets > as redirect
reveal 'ast://./src?complexity>10'

# Find functions that are complex AND long
reveal 'ast://./src?complexity>8&lines>50'
```

### Wildcard Name Search

```bash
# All test functions
reveal 'ast://.?name=test_*'

# All helper functions
reveal 'ast://src/?name=*helper*'

# Single character wildcard
reveal 'ast://.?name=get_?'

# Combine with type filter
reveal 'ast://.?name=*Manager&type=class'
```

### Find Refactoring Candidates

```bash
# Long but simple functions (copy-paste territory)
reveal 'ast://./src?lines>50&complexity<5'

# Functions with too many parameters
reveal 'ast://./src?type=function' --format=json | \
  jq '.results[] | select(.signature | split(",") | length > 5)'
```

### Cross-Codebase Analysis

```bash
# Find all get_* methods across entire project
reveal 'ast://.?name=get_*' --format=json | \
  jq -r '.results[] | "\(.file):\(.line) \(.name)"'

# Count functions per file
reveal 'ast://./src?type=function' --format=json | \
  jq -r '.results[].file' | sort | uniq -c | sort -rn

# Find largest classes (potential god objects)
reveal 'ast://./src?type=class' --format=json | \
  jq -r '[.results[] | {name, file, lines: .line_count}] |
         sort_by(.lines) | reverse | .[0:10][] |
         "\(.file) - \(.name) (\(.lines) lines)"'

# Complexity distribution analysis
reveal 'ast://./src?type=function' --format=json | \
  jq '[.results[].complexity] | group_by(.) |
      map({complexity: .[0], count: length}) |
      sort_by(.complexity) | reverse'
```

### Decorator Intelligence (NEW v0.23.0)

```bash
# Find all @property methods
reveal 'ast://.?decorator=property'

# Find all cached functions (wildcards work!)
reveal 'ast://.?decorator=*cache*'

# Find abstract interface methods
reveal 'ast://.?decorator=abstractmethod'

# Find complex properties (code smell - properties should be simple)
reveal 'ast://.?decorator=property&lines>10'

# Find all @dataclass classes
reveal 'ast://.?decorator=dataclass&type=class'
```

### Decorator Statistics

```bash
# Analyze decorator usage across your codebase
reveal src/ --decorator-stats

# Output shows:
# - Standard library decorators (@property, @staticmethod, etc.)
# - Custom/third-party decorators
# - Occurrence counts and file distribution
# - Summary with total decorators and coverage percentage
```

### Filter Typed Output

```bash
# Show only properties in typed view
reveal app.py --typed --filter=property

# Show only static methods
reveal app.py --typed --filter=staticmethod

# Show only classes
reveal app.py --typed --filter=class
```

---

## Pipeline Magic

### Changed Files Analysis

```bash
# What changed in git? Show structure
git diff --name-only | reveal --stdin --outline

# Check quality of changed Python files
git diff --name-only | grep '\.py$' | reveal --stdin --check

# Find complex functions in changed files
git diff --name-only | grep '\.py$' | \
  while read f; do reveal "ast://$f?complexity>8"; done
```

### Batch Processing with JSON

```bash
# All functions > 100 lines across project
find . -name "*.py" | reveal --stdin --format=json | \
  jq -r '.structure.functions[] | select(.line_count > 100) |
         "\(.file):\(.line) \(.name) [\(.line_count) lines]"'

# Extract all imports
find . -name "*.py" | reveal --stdin --format=json | \
  jq -r '.structure.imports[].content' | sort -u
```

### PR Review Workflow

```bash
# 1. See what changed
git diff --name-only origin/main | reveal --stdin

# 2. Check quality issues
git diff --name-only origin/main | grep '\.py$' | reveal --stdin --check

# 3. Find new complex functions
git diff --name-only origin/main | grep '\.py$' | \
  xargs -I{} reveal 'ast://{}?complexity>10'
```

---

## Markdown Surgery

### Extract All Links

```bash
reveal README.md --links

# Filter by type
reveal README.md --links --link-type=external  # GitHub, APIs
reveal README.md --links --link-type=internal  # Local files
reveal README.md --links --link-type=email     # mailto:

# Filter by domain
reveal README.md --links --domain=github.com
```

### Find Broken Links

```bash
# reveal automatically marks broken internal links with [BROKEN]
reveal docs/*.md --links 2>/dev/null | grep BROKEN
```

### Extract Code Examples

```bash
# All code blocks
reveal README.md --code

# Only Python examples
reveal README.md --code --language=python

# Include inline code too
reveal README.md --code --inline
```

### Navigate Documentation

```bash
# Get structure of a doc
reveal docs/ARCHITECTURE.md --outline

# Extract specific section
reveal docs/ARCHITECTURE.md "Installation"

# Find all headings
reveal docs/*.md --format=json | jq '.structure.headings[].content'
```

---

## Token Efficiency Mastery

### Progressive Disclosure Pattern

```bash
# Level 1: Structure (~100 tokens)
reveal app.py

# Level 2: Hierarchy (~150 tokens)
reveal app.py --outline

# Level 3: Specific extraction (~50 tokens)
reveal app.py process_data

# Compare: cat app.py (~7,500 tokens for 300 lines)
# Savings: 50-150x
```

### Semantic Slicing

```bash
# First 5 functions only
reveal large_module.py --head 5

# Last 3 functions (bugs cluster at the bottom!)
reveal large_module.py --tail 3

# Specific range
reveal conversation.jsonl --range 48-52
```

### URI Progressive Disclosure

```bash
# Python environment
reveal python://              # Overview (~20 tokens)
reveal python://packages      # Package list (~200 tokens)
reveal python://packages/numpy  # Specific package (~50 tokens)

# AST queries
reveal ast://./src            # All structure (~500 tokens)
reveal 'ast://./src?complexity>10'  # Just complex ones (~100 tokens)
```

---

## Quality Gatekeeping

### Comprehensive Checks

```bash
# Run all checks
reveal app.py --check

# Just bugs and security
reveal app.py --check --select B,S

# Everything except line length
reveal app.py --check --ignore E501

# Complexity-focused check (find refactoring targets)
reveal app.py --check --select C901,C902,C905
```

### Codebase Health Assessment

```bash
# Get overall stats with hotspots
reveal stats://./src --hotspots

# Output shows:
# - Total files, lines, functions, classes
# - Average complexity and quality score
# - Top 10 files needing attention (hotspot score)
# - Issues: functions >100 lines, depth >4, etc.

# Track complexity over time (save baseline)
reveal stats://./src --format=json > complexity_baseline.json

# Compare later (manually with jq)
reveal stats://./src --format=json > complexity_current.json
jq -s '.[0].summary.avg_complexity as $old |
       .[1].summary.avg_complexity as $new |
       "Complexity: \($old) → \($new) (change: \(($new - $old) * 100 | round / 100))"' \
  complexity_baseline.json complexity_current.json
```

### Available Rules

```bash
# List all rules
reveal --rules

# Explain a specific rule
reveal --explain B001

# Rules by category (24 total):
# B - Bugs: B001 bare except, B002 @staticmethod+self, B003 complex @property, B004 @property no return [NEW v0.23.0]
# C - Complexity: C901 cyclomatic, C902 function length, C905 nesting depth
# D - Duplicates: D001 duplicate functions, D002 similar code
# E - Errors: E501 line length
# M - Maintainability: M101 file too large
# N - Nginx: N001 duplicate backends, N002 missing SSL, N003 missing proxy headers
# R - Refactoring: R913 too many arguments
# S - Security: S701 Docker :latest tag
# U - URLs: U501 insecure http://
# V - Validation: V001-V007 schema/structure validation
```

### Combine with Outline

```bash
# See structure AND issues together
reveal app.py --outline --check
```

### Docker Security

```bash
# Check Dockerfile best practices
reveal Dockerfile --check

# S701: Warns about :latest tags
# Recommends pinning to specific versions
```

### Nginx Configuration Validation (NEW v0.19.0)

```bash
# Check nginx config for common issues
reveal /etc/nginx/nginx.conf --check
reveal /etc/nginx/sites-available/*.conf --check

# N001: Duplicate backends (multiple upstreams → same server:port)
# N002: SSL servers missing certificate directives
# N003: Proxy locations missing X-Real-IP, X-Forwarded-For

# Example: Catch the $8K incident class
reveal /etc/nginx/conf.d/upstreams.conf --check --select N001
# ❌ N001 Upstream 'app2' shares backend 127.0.0.1:8000 with 'app1'
```

**Why this matters:** A production incident where two nginx upstreams pointed to the same port caused a $8,619/month revenue site to serve the wrong content. N001 catches this exact class of bug.

---

## Discovery Patterns

### Self-Documenting Help System

```bash
# Level 1: What adapters exist? (~50 tokens)
reveal help://

# Level 2: How do I use this adapter? (~200 tokens)
reveal help://ast
reveal help://python
reveal help://env

# Level 3: Deep dive (~2000 tokens)
reveal help://python-guide
reveal help://anti-patterns
reveal help://adapter-authoring
```

### Explore Unknown Codebase

```bash
# 1. Directory structure
reveal src/

# 2. Find entry points
reveal 'ast://./src?name=main*'
reveal 'ast://./src?name=*cli*'

# 3. Find the big modules
reveal 'ast://./src?lines>100'

# 4. Understand one file
reveal src/important_module.py --outline
```

### Find What You're Looking For

```bash
# Instead of: grep -r "class UserManager"
reveal 'ast://.?name=UserManager&type=class'

# Instead of: find . -name "*.py" -exec grep -l "def process"
reveal 'ast://.?name=process*&type=function'
```

---

## Format Transformations

### JSON for Scripting

```bash
# Structure as JSON
reveal app.py --format=json

# Query with jq
reveal app.py --format=json | jq '.structure.functions | length'
reveal app.py --format=json | jq '.structure.imports[].content'
```

### Typed JSON (with Relationships)

```bash
# Get typed output with metadata
reveal app.py --format=typed

# Includes:
# - Entity types (function, class, import)
# - Relationships (calls, inherits)
# - Line ranges
```

### Grep-Compatible Output

```bash
# Pipeable format
reveal app.py --format=grep

# Output: file:line:content
# Perfect for: reveal ... | grep pattern | cut -d: -f1-2
```

---

## JSON Deep Dive (json:// Adapter)

The `json://` adapter turns reveal into a powerful JSON explorer—no jq required for basic operations.

### Explore Unknown JSON Structure

```bash
# What's in this JSON file?
reveal json://config.json?schema

# Output:
# Schema:
# {
#   "database": {
#     "host": "str",
#     "port": "int",
#     "credentials": {
#       "username": "str",
#       "password": "str"
#     }
#   },
#   "features": "Array[str]"
# }
```

**Why this matters:** AI agents constantly work with `package.json`, `tsconfig.json`, API responses. Schema inference shows structure without reading the whole file.

### Navigate to Specific Keys

```bash
# Get nested value
reveal json://package.json/scripts
reveal json://config.json/database/host

# Array access
reveal json://data.json/users/0           # First user
reveal json://data.json/users[0:3]        # First 3 users (slice)
```

### Search Inside JSON (Gron-Style)

```bash
# Flatten to grep-able format
reveal json://config.json?flatten

# Output:
# json = {}
# json.database = {}
# json.database.host = "localhost"
# json.database.port = 5432
# json.database.credentials = {}
# json.database.credentials.username = "admin"

# Now search!
reveal json://config.json?flatten | grep -i password
reveal json://large-config.json?flatten | grep 'api.*key'
```

### Real-World Patterns

```bash
# Explore package.json
reveal json://package.json?schema           # See structure
reveal json://package.json/dependencies     # List deps
reveal json://package.json/scripts          # See npm scripts

# Explore tsconfig.json
reveal json://tsconfig.json/compilerOptions
reveal json://tsconfig.json?flatten | grep strict

# Debug API response (saved to file)
reveal json://api-response.json?schema      # Understand structure
reveal json://api-response.json/data/0      # First result
```

### Compare: json:// vs cat + jq

```bash
# ❌ Old way
cat config.json | jq '.database.host'

# ✅ Reveal way
reveal json://config.json/database/host

# ❌ Old way (understand structure)
cat large.json | jq 'keys'
cat large.json | jq '.[0] | keys'

# ✅ Reveal way
reveal json://large.json?schema
```

**Token savings:** For AI agents, `json://?schema` gives structure understanding in ~100 tokens vs ~5000 tokens for the full file.

---

## Multi-Language Exploration

### Built-in Analyzers (Full Support)

```bash
# Python, JS, TS, Rust, Go, Dockerfile, YAML, JSON, TOML, Markdown
reveal app.py            # Python
reveal config.yaml       # YAML
reveal Dockerfile        # Dockerfile with quality checks
reveal package.json      # JSON structure
reveal main.go           # Go
reveal lib.rs            # Rust
```

### Tree-Sitter Fallback (37+ Languages)

```bash
# C, C++, Java, Ruby, PHP, Scala, Haskell, OCaml, Lua...
reveal Main.java         # Works!
reveal app.rb            # Works!
reveal script.lua        # Works!

# Check what's supported
reveal --list-supported
```

### Nginx Config Analysis

```bash
# See all server blocks
reveal nginx.conf

# Extract specific server
reveal nginx.conf server_myapp

# Find all upstreams
reveal nginx.conf --format=json | jq '.structure.upstreams'
```

### Jupyter Notebooks

```bash
# See notebook structure
reveal analysis.ipynb

# All cells with outputs
reveal analysis.ipynb --format=json
```

---

## Power User Combos

### The Full Investigation

```bash
# Something's broken. Find it.
reveal python://doctor                           # Environment OK?
reveal python://debug/bytecode                   # Stale cache?
reveal python://module/broken_module             # Import conflict?
reveal 'ast://./src?complexity>10'               # Spaghetti code?
reveal ./src --check --select B,S                # Bugs? Security?
```

### The Code Review

```bash
# PR review speedrun
git diff --name-only origin/main > /tmp/changed
cat /tmp/changed | reveal --stdin --outline      # What changed?
cat /tmp/changed | grep '\.py$' | reveal --stdin --check  # Quality?
git diff --name-only origin/main | xargs -I{} reveal 'ast://{}?complexity>10'  # Complex?
```

### The Documentation Audit

```bash
# Docs healthy?
reveal docs/ --links | grep BROKEN               # Broken links?
reveal docs/*.md --code --language=bash          # All CLI examples
reveal 'ast://docs?type=heading'                 # Document structure
```

### The Performance Hunt

```bash
# Find optimization targets
reveal 'ast://./src?lines>100'                   # Big functions
reveal 'ast://./src?complexity>15'               # Complex functions
reveal 'ast://./src?lines>50&complexity<3'       # Long but simple (inline?)
```

---

## Quick Reference

| Task | Command |
|------|---------|
| Structure | `reveal file.py` |
| Hierarchy | `reveal file.py --outline` |
| Extract | `reveal file.py function_name` |
| Complex | `reveal 'ast://.?complexity>10'` |
| Very complex | `reveal 'ast://.?complexity>20'` |
| Complex+long | `reveal 'ast://.?complexity>15&lines>100'` |
| Top complex | `reveal 'ast://.?type=function' --format=json \| jq -r '[.results[]] \| sort_by(.complexity) \| reverse \| .[0:10][]'` |
| Long | `reveal 'ast://.?lines>50'` |
| God functions | `reveal 'ast://.?complexity>30\|lines>150'` |
| Named | `reveal 'ast://.?name=test_*'` |
| Decorated | `reveal 'ast://.?decorator=property'` |
| Cached | `reveal 'ast://.?decorator=*cache*'` |
| Dec stats | `reveal src/ --decorator-stats` |
| Filter | `reveal file.py --typed --filter=property` |
| Check | `reveal file.py --check` |
| Complexity check | `reveal file.py --check --select C901,C902,C905` |
| Stats | `reveal stats://./src --hotspots` |
| Links | `reveal doc.md --links` |
| Code | `reveal doc.md --code` |
| Pipeline | `git diff --name-only \| reveal --stdin` |
| Python env | `reveal python://doctor` |
| Imports | `reveal python://module/name` |
| JSON output | `reveal file.py --format=json` |
| JSON schema | `reveal json://config.json?schema` |
| JSON path | `reveal json://config.json/database/host` |
| JSON search | `reveal json://config.json?flatten \| grep key` |
| Slice | `reveal file.py --head 5` |
| Help | `reveal help://` |

---

## See Also

- [AGENT_HELP.md](AGENT_HELP.md) - Quick reference for AI agents
- [MARKDOWN_GUIDE.md](MARKDOWN_GUIDE.md) - Core functionality guide
- [CONFIGURATION_GUIDE.md](CONFIGURATION_GUIDE.md) - Customize behavior
- [ANTI_PATTERNS.md](ANTI_PATTERNS.md) - What NOT to do
- [README.md](README.md) - Documentation hub
- [GitHub Issues](https://github.com/semantic-infrastructure-lab/reveal/issues) - Feature requests and roadmap

---

*Part of [Semantic Infrastructure Lab](https://github.com/semantic-infrastructure-lab/sil)*
