# Code Structure Exploration

**Goal: Get outline/index of large files without reading entire file.**

## Strategy: Tiered Approach

Try tools in this order (stop when you get what you need):
1. **ast-grep** - Targeted pattern extraction (fastest when pattern known)
2. **Language-specific tools** - Best quality, language-aware
3. **ctags** - Universal fallback, simple
4. **Read file** - Last resort (but now you know it's worth it)

---

# Method 1: ast-grep (Targeted Extraction)

**Best when:** You know what patterns to look for

## JavaScript/TypeScript

### List all exported functions
```bash
ast-grep -l typescript -p 'export function $NAME($$$)' file.ts
```

### List all class definitions
```bash
ast-grep -l typescript -p 'export class $NAME { $$$ }' file.ts
```

### List all interface definitions
```bash
ast-grep -l typescript -p 'interface $NAME { $$$ }' file.ts
```

### List all type definitions
```bash
ast-grep -l typescript -p 'type $NAME = $$$' file.ts
```

### Find all imports
```bash
ast-grep -l typescript -p 'import $WHAT from $WHERE' file.ts
```

### Combine patterns for full outline
```bash
# Get exports, classes, interfaces, types in one go
ast-grep -l typescript -p 'export function $NAME($$$)' file.ts
ast-grep -l typescript -p 'export class $NAME' file.ts
ast-grep -l typescript -p 'interface $NAME' file.ts
ast-grep -l typescript -p 'type $NAME' file.ts
```

## Python

### List all function definitions
```bash
ast-grep -l python -p 'def $NAME($$$):' file.py
```

### List all class definitions
```bash
ast-grep -l python -p 'class $NAME:' file.py
ast-grep -l python -p 'class $NAME($$$):' file.py  # With inheritance
```

### List all imports
```bash
ast-grep -l python -p 'import $NAME' file.py
ast-grep -l python -p 'from $MODULE import $$$' file.py
```

## Go

### List all function definitions
```bash
ast-grep -l go -p 'func $NAME($$$) $$$ { $$$ }' file.go
```

### List all type definitions
```bash
ast-grep -l go -p 'type $NAME struct { $$$ }' file.go
ast-grep -l go -p 'type $NAME interface { $$$ }' file.go
```

### List all exported functions (capitalized)
```bash
ast-grep -l go -p 'func $NAME($$$)' file.go | rg -e '^[A-Z]'
```

## Rust

### List all function definitions
```bash
ast-grep -l rust -p 'fn $NAME($$$) { $$$ }' file.rs
ast-grep -l rust -p 'pub fn $NAME($$$) { $$$ }' file.rs  # Public only
```

### List all struct definitions
```bash
ast-grep -l rust -p 'struct $NAME { $$$ }' file.rs
```

### List all trait definitions
```bash
ast-grep -l rust -p 'trait $NAME { $$$ }' file.rs
```

---

# Method 2: Language-Specific Tools

**Best when:** Available and well-supported for the language

## Go: go doc

### List package contents
```bash
go doc ./path/to/package
```

### List specific file symbols
```bash
go doc -all ./path/to/package | rg -e '^func|^type'
```

This is ideal for Go - uses actual compiler, understands exports, very reliable.

## Python: Language-specific options

### Using Python's inspect module (if interactive)
```bash
python3 -c "import ast; import sys; tree = ast.parse(open('file.py').read()); print([node.name for node in ast.walk(tree) if isinstance(node, (ast.FunctionDef, ast.ClassDef))])"
```

More complex but accurate.

## JavaScript/TypeScript: Language Server (if available)

Some projects have LSP tooling that can extract symbols. Variable availability.

---

# Method 3: ctags/universal-ctags (Universal Fallback)

**Best when:** Need quick universal solution across languages

## Basic Usage

### Generate tags for single file
```bash
ctags -f - file.js
```
Output format: `symbol<tab>file<tab>line<tab>type`

### Common output (shows functions, classes, etc.)
```bash
ctags -f - file.ts | grep -v '^!' | cut -f1,4
```
Shows symbol names and types.

### Filter by type
```bash
# Functions only
ctags -f - file.py --kinds-Python=f

# Classes only
ctags -f - file.py --kinds-Python=c

# Functions and classes
ctags -f - file.py --kinds-Python=fc
```

### Language-specific kinds

Common types:
- `f` - functions
- `c` - classes
- `m` - methods
- `v` - variables
- `i` - interfaces (TypeScript)
- `t` - types (TypeScript/Go)

### Pretty output
```bash
ctags -f - --fields=+n file.ts | grep -v '^!' | awk '{print $4 " " $1 " (line " $3 ")"}'
```
Shows: type, name, line number

## Limitations

- May miss some language-specific constructs
- Doesn't understand semantic context
- But works across many languages with simple interface

---

# Integration Strategy

## Use Case: Explore Large Unknown File

**Step 1: Get quick outline**
```bash
# Try ast-grep with common patterns first
ast-grep -l typescript -p 'export function $NAME' file.ts
ast-grep -l typescript -p 'export class $NAME' file.ts

# Or use ctags for quick overview
ctags -f - file.ts | grep -v '^!' | cut -f1,4 | sort -u
```

**Step 2: Decide what to investigate**
Based on names, pick interesting functions/classes.

**Step 3: Use ast-grep for targeted search**
```bash
# Found "processData" function, now see how it's called
ast-grep -l typescript -p 'processData($$$)' .
```

**Step 4: Read selectively**
Now read just the relevant sections, not the entire file.

## Use Case: "What does this file export?"

```bash
# JavaScript/TypeScript
ast-grep -l typescript -p 'export $WHAT' file.ts

# Python
ast-grep -l python -p 'def $NAME($$$):' file.py | rg -e '^[^_]'  # Non-private

# Go (exported = capitalized)
go doc ./path/to/package
```

## Use Case: "What classes/interfaces are available?"

```bash
# TypeScript
ast-grep -l typescript -p 'interface $NAME { $$$ }' file.ts
ast-grep -l typescript -p 'class $NAME { $$$ }' file.ts

# Python
ast-grep -l python -p 'class $NAME' file.py

# Go
ast-grep -l go -p 'type $NAME struct { $$$ }' file.go
```

---

# Decision Flow

```
Need to understand large file?
│
├─ Know what patterns to look for? (exports, classes, etc.)
│  → Use ast-grep with specific patterns
│  → Fast, targeted, precise
│
├─ Go language file?
│  → Use `go doc` for package/file
│  → Best quality, compiler-aware
│
├─ Need universal quick outline?
│  → Use ctags
│  → Simple, works across languages
│
├─ Need detailed understanding?
│  → Read file (selectively based on outline)
│  → Use outline to guide what sections to read
│
└─ Exploring multiple files?
   → Combine: get outline of each, identify relevant ones, read those
```

---

# Best Practices

## 1. Start with Cheapest Tool
```bash
# Fast: ast-grep with known pattern
ast-grep -l typescript -p 'export function $NAME' file.ts

# Medium: ctags for overview
ctags -f - file.ts | cut -f1

# Expensive: Read entire file
# Only after outline shows it's relevant
```

## 2. Combine with grep for Filtering
```bash
# Get all functions, filter to exported (capitalized in Go)
ast-grep -l go -p 'func $NAME($$$)' file.go | rg -e '^func [A-Z]'

# Get ctags output, filter to public methods
ctags -f - file.py | rg -e '\tm\t' | rg -e '^[^_]'
```

## 3. Use Outline to Guide Detailed Reading
Don't read blindly. Get outline, identify relevant sections, then read those.

## 4. Cache Results for Large Explorations
If exploring many files:
```bash
# Generate tags for entire directory
ctags -R -f .tags .

# Query as needed
grep 'functionName' .tags
```

## 5. Verify with Read When Needed
Outlines give structure but not implementation. When you need details, read the specific section.

---

# Common Workflows

## "What's in this 2000-line file?"
```bash
# Quick outline
ast-grep -l typescript -p 'export function $NAME' large-file.ts
ast-grep -l typescript -p 'export class $NAME' large-file.ts

# Or ctags
ctags -f - large-file.ts | grep -v '^!' | cut -f1,4 | sort
```

## "Find all API endpoints in this file"
```bash
# Express.js
ast-grep -l javascript -p 'router.$METHOD($$$)' routes.js

# Or search for specific pattern
ast-grep -l javascript -p 'app.get($$$)' app.js
```

## "What classes are in this Python module?"
```bash
ast-grep -l python -p 'class $NAME:' module.py
```

## "What does this Go package export?"
```bash
go doc ./path/to/package
```

---

# Limitations and Fallbacks

## When Tools Fail

**ast-grep**: Requires knowing patterns
- Fallback: Try ctags or Read

**ctags**: May miss complex constructs
- Fallback: Use ast-grep with specific patterns or Read

**Language tools**: May not be available
- Fallback: Try ctags or ast-grep

## When to Just Read

Sometimes reading is the right answer:
- File is <500 lines
- Outline doesn't give enough context
- Need to understand implementation
- Tools don't support the language/construct

**The outline told you it's worth reading** - that's still a win.

---

# Summary

**Primary strategy: ast-grep for targeted extraction**
```bash
ast-grep -l LANG -p 'export function $NAME' file
```

**Universal fallback: ctags**
```bash
ctags -f - file | grep -v '^!' | cut -f1,4
```

**Go-specific: go doc**
```bash
go doc ./path/to/package
```

**Key principle:**
**Get outline → Decide what's relevant → Read selectively**

**Don't read 1000-line files blind. Use structure tools to guide your reading.**