---
name: ast-grep-repo-index
description: Building a structural map of an unfamiliar repository — entry points, module boundaries, and where the real logic lives.
when_to_use: You are mapping a codebase you did not write, before changing anything in it.
tags: [analysis, codebase]
---

# Map the shape before reading the code

An unfamiliar repository is mostly scaffolding. The goal of a first pass is to
find the small fraction that matters and ignore the rest deliberately.

## Start at the edges, not the top

```bash
rg -l 'fn main\(|async fn main' --type rust        # entry points
rg -n 'route\(|\.get\(|\.post\(' | head -50        # HTTP surface
ls migrations/ | tail -20                          # what the data recently grew
```

Entry points, the request surface and the schema tell you what the system *does*
in about ten minutes. Reading `lib.rs` top-down tells you how it is organised,
which is a different and less useful question early on.

## Size is a signal

```bash
find . -name '*.rs' -not -path './target/*' | xargs wc -l | sort -rn | head -20
```

The largest files are either the core logic or an accumulation nobody split.
Both are worth knowing before you touch anything nearby.

## Structural search beats text search for call graphs

Text grep for a function name matches its definition, its calls, its doc
comments and any string containing it. When you need call sites specifically,
search the shape — `ast-grep --pattern 'foo($$$)'` — or at minimum anchor the
text: `rg '\bfoo\('.

## Follow one request end to end

The single most valuable early exercise: pick one endpoint and trace it from
route registration to database and back. It crosses every layer the codebase
has, in the order the codebase thinks about them, and it tells you more than any
architecture document. See `request-lifecycle-tracing`.

## Write down the map

A map that lives only in your head has to be rebuilt by the next person. Record
entry points, the three or four modules with the real logic, and — most
valuable — what you *expected* to find and did not. The gaps between a reasonable
mental model and the actual structure are where future bugs live.