codebase-viewer

name	codebase-viewer
description	Structured codebase intelligence: directory tree with roles, entry points, dependency graph, test coverage map, and annotated 'here be dragons' warnings.
triggers	["view codebase","map the code","codebase overview","show me the architecture","explore this repo"]
version	1.0.0
model	sonnet

Codebase Viewer

Produces a structured codebase map — not a file listing but an annotated architecture view with entry points, dependency flow, test coverage, and danger zones.

Workflow

1. TREE

Generate directory structure (2-3 levels deep) with role annotations:

• Each directory gets a one-line role description
• Mark directories as: source, test, config, docs, build, generated, vendored
• Flag empty directories and their likely purpose
• Respect .gitignore — skip node_modules, vendor, build outputs

2. ENTRY

Identify entry points — where execution begins:

• main functions (Go, Rust, Python)
• CLI command handlers
• HTTP route registrations
• Event listeners and subscribers
• Scheduled task definitions
• Test suites (as secondary entry points)

3. DEPS

Map the dependency graph:

• External dependencies from go.mod / package.json / Cargo.toml / requirements.txt
• Internal package import relationships
• Circular dependency detection
• Heavyweight dependencies (large transitive dep trees)

4. TESTS

Scan for test coverage:

• Which packages/directories have test files
• Test-to-source ratio per directory
• Packages with zero tests (flag as risk)
• Test patterns in use (unit, integration, e2e, benchmark)

5. PATTERNS

Identify architectural patterns:

• Clean architecture / hexagonal / onion (ports-and-adapters)
• MVC / MVVM
• Microservice boundaries
• Monolith with internal module separation
• Event-driven / message-passing
• Repository pattern / service layer

6. DRAGONS

Flag areas of concern — severity-labeled:

• CRITICAL: Files >1000 lines, circular dependencies, hardcoded secrets
• WARNING: Files >500 lines, deeply nested code (>4 levels), TODO/FIXME density >5 per file
• INFO: No tests for package, outdated dependencies, unused imports

7. CONTRACTS

Identify interfaces and API boundaries:

• Go interfaces and their implementors
• HTTP API surface (routes, methods, request/response types)
• gRPC / protobuf definitions
• Event schemas
• Configuration contracts (env vars, config files)

8. REPORT

Produce structured codebase map as markdown:

• Header with repo name, language, size metrics
• Each section from above as a headed section
• Summary statistics table (files, lines, packages, test coverage %)

9. SUGGEST (optional, only if requested)

Based on findings, suggest 3 high-value improvements:

• Highest-risk dragon to address first
• Biggest test coverage gap
• Most impactful architectural improvement

Reading Rules

• For files >50KB: use Grep to find relevant sections, then read with offset/limit
• Never read files >200KB in one shot
• Check file size with wc -c before reading large files
• Prefer targeted reads over full-file reads for analysis