Metadata-Version: 2.4
Name: reveal-cli
Version: 0.75.1
Summary: How AI agents understand codebases without wasting tokens — local-first, adapter-driven, progressive disclosure enforced by design
Author-email: Progressive Reveal Contributors <scottsen@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/Semantic-Infrastructure-Lab/reveal
Project-URL: Repository, https://github.com/Semantic-Infrastructure-Lab/reveal
Project-URL: Documentation, https://github.com/Semantic-Infrastructure-Lab/reveal/tree/main/docs
Project-URL: Bug Tracker, https://github.com/Semantic-Infrastructure-Lab/reveal/issues
Project-URL: Discussions, https://github.com/Semantic-Infrastructure-Lab/reveal/discussions
Project-URL: Changelog, https://github.com/Semantic-Infrastructure-Lab/reveal/releases
Keywords: cli,code-analysis,ast,semantic-diff,progressive-disclosure,code-exploration,python,tree-sitter
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.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.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema>=4.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Requires-Dist: rich>=13.0.0
Requires-Dist: tree-sitter>=0.25.2
Requires-Dist: tree-sitter-language-pack>=0.13.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: mccabe>=0.7.0
Requires-Dist: cryptography>=41.0.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"
Requires-Dist: numpy>=1.20.0; extra == "dev"
Requires-Dist: pymysql>=1.0.0; extra == "dev"
Requires-Dist: dnspython>=2.0.0; extra == "dev"
Requires-Dist: mcp>=1.0.0; extra == "dev"
Requires-Dist: pygit2>=1.14.0; extra == "dev"
Provides-Extra: treesitter
Provides-Extra: html
Requires-Dist: lxml>=4.9.0; extra == "html"
Provides-Extra: database
Requires-Dist: pymysql>=1.0.0; extra == "database"
Provides-Extra: git
Requires-Dist: pygit2>=1.14.0; extra == "git"
Provides-Extra: whois
Requires-Dist: python-whois>=0.9.0; extra == "whois"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: xlsx
Requires-Dist: openpyxl>=3.1.0; extra == "xlsx"
Provides-Extra: powerpivot
Requires-Dist: pbixray>=0.5.0; extra == "powerpivot"
Dynamic: license-file

# Reveal

**Reveal is how AI agents understand codebases without wasting tokens.**

A local-first, adapter-driven semantic inspection layer — progressive disclosure enforced by design. One CLI, 23 URI adapters, 190+ languages. Structure before content, always. Engineers and AI systems use the same tool, the same syntax, the same progressive drill-down.

```bash
reveal src/auth.py validate_token           # What does this function do?
reveal 'calls://src/?target=validate_token' # Who calls it? (cross-file)
reveal overview .                           # one-glance dashboard: quality, activity, deps
reveal 'ast://src/?complexity>10'           # What's too complex?
reveal health ssl://api.example.com domain://example.com ./src  # One-shot health check
reveal pack src/ --since main --budget 8000 # PR context snapshot for AI agents
```

## Installation

```bash
pip install reveal-cli
```

## What Makes It Different

**Progressive disclosure — the only way in.** `dir → file → element` isn't optional; it's the architecture. You cannot accidentally dump 7,000 tokens of raw code.

```bash
reveal src/                          # tree structure (~50-200 tokens)
reveal src/auth.py                   # imports, functions, classes (~200-500 tokens)
reveal src/auth.py validate_token    # exact code (~100-300 tokens)
```

**Local-first.** No backend, no API keys, no data leaving the machine. Runs in CI/CD pipelines, air-gapped environments, and anywhere you'd use a Unix tool.

**Everything is a URI.** `ast://`, `calls://`, `ssl://`, `mysql://`, `markdown://`, `claude://` — same query operators, same output format, same piping model across all of them.

**Cross-file call graph analysis:**
```bash
reveal 'calls://src/?target=fn&depth=3'    # full impact radius before a refactor
reveal 'calls://src/?rank=callers&top=20'  # most architecturally coupled functions
reveal 'calls://src/?uncalled'             # functions with no callers — rough check, verify results
```

**PR-aware context snapshots for AI agents:**
```bash
reveal pack src/ --since main --budget 8000   # changed files first, then key dependencies
reveal pack src/ --focus "auth" --budget 6000 # topic-focused snapshot
```

**Composable pipelines:**
```bash
# nginx config → extract all domains → check each SSL cert
reveal nginx.conf --extract domains | sed 's/^/ssl:\/\//' | reveal --stdin --check

# Find functions that got more complex in this PR
reveal diff://git://main/.:git://HEAD/. --format json | \
  jq '.diff.functions[] | select(.complexity_delta > 5)'

# Batch SSL check from a file of domains
reveal @domains.txt --check
```

**Native MCP server (`reveal-mcp`) for AI agent integration:**
```bash
# Install once, works in Claude Code, Cursor, Windsurf, any MCP-compatible agent
pip install reveal-cli
reveal-mcp  # starts the server
# Five tools: reveal_structure, reveal_element, reveal_query, reveal_pack, reveal_check
# Agents get progressive disclosure and call-graph analysis — no subprocess overhead
```

**Unified health checks across categories:**
```bash
reveal health ./src ssl://api.example.com domain://example.com mysql://prod
# → code quality + cert expiry + DNS health + DB replication, one exit code
```

**Documentation as a queryable graph:**
```bash
reveal 'markdown://docs/?aggregate=type'         # taxonomy frequency table
reveal 'markdown://docs/?link-graph'             # bidirectional link analysis + orphan detection
reveal 'markdown://docs/?body-contains=retry&type=procedure'  # full-text + metadata
```

**AI session history as structured data** *(useful for workflows built on Claude Code)*:
```bash
reveal claude://sessions/                          # list all sessions
reveal 'claude://sessions/?search=validate_token' # cross-session search
```

## What Reveal Does (and Doesn't)

| Reveal does | Reveal does not |
|-------------|-----------------|
| Inspect / read | Modify / write |
| Evaluate quality | Auto-fix issues |
| Package for LLMs | Run LLM inference |
| Compose workflows | Orchestrate pipelines |
| Describe itself | Require external config |

## Subcommands

```bash
reveal check src/              # quality check (complexity, maintainability, links)
reveal review main..HEAD       # PR review: diff + check + hotspots, one pass
reveal health ssl://site.com   # health check with exit codes 0/1/2
reveal pack src/ --budget 8000 # token-budgeted snapshot for LLM context
reveal hotspots src/           # top complexity hotspots
reveal overview .              # one-glance dashboard: stats, quality, git activity
reveal deps .                  # dependency health: circular imports, unused, packages
reveal dev new-adapter <name>  # scaffold new adapters/rules
```

## Adapters (22 built-in)

| Adapter | What it queries |
|---------|-----------------|
| `ast://` | Functions, classes, complexity, decorators — 190+ languages |
| `calls://` | Cross-file call graph: callers, callees, coupling metrics, dead code |
| `diff://` | Structural diff between branches or commits (with per-function complexity delta) |
| `imports://` | Dependency graph, circular imports, unused imports |
| `stats://` | Codebase quality scores, hotspots, duplication |
| `git://` | Commits, blame, branches, tags, function-level history |
| `ssl://` | Certificate expiry, chain validation, hostname match |
| `autossl://` | cPanel AutoSSL run logs — per-domain TLS outcomes, DCV failures |
| `letsencrypt://` | Let's Encrypt certbot live certificates — expiry, multi-domain, renewal status |
| `domain://` | DNS, WHOIS, registrar, HTTP redirect chain, email DNS |
| `nginx://` | Config parsing, ACL rules, upstream routing, ACME validation |
| `cpanel://` | User environment, domains, SSL health, ACL audit |
| `mysql://` | Schema, replication status, table analysis |
| `sqlite://` | Schema, query analysis |
| `markdown://` | Frontmatter, headings, link graphs, full-text search |
| `json://` | JMESPath queries, nested navigation, flatten |
| `env://` | Environment variable analysis, `.env` validation |
| `python://` | Runtime introspection of live Python modules |
| `xlsx://` | Excel data extraction and analysis |
| `claude://` | AI session history, tool usage, file access patterns |
| `reveal://` | Reveal introspects itself: adapters, rules, config |
| `help://` | Built-in documentation, searchable from the CLI |

## Documentation

- **[Why Reveal](reveal/docs/WHY_REVEAL.md)** — what makes it powerful
- **[Quick Start](reveal/docs/QUICK_START.md)** — 5-minute introduction
- **[MCP Server](reveal/docs/guides/MCP_SETUP.md)** — native integration with Claude Code, Cursor, Windsurf
- **[CI/CD Recipes](reveal/docs/guides/CI_RECIPES.md)** — GitHub Actions and GitLab CI ready-to-paste YAML
- **[Benchmarks](reveal/docs/BENCHMARKS.md)** — measured 3.9–15x token reduction on real scenarios
- **[Recipes](reveal/docs/guides/RECIPES.md)** — task-based workflows
- **[All Docs](reveal/docs/INDEX.md)** — complete documentation index
- **AI Agents**: `reveal --agent-help`

## License

See [LICENSE](LICENSE) for details.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
