Reverse Engineer To learn: How will you design a code assist

https://grasprepo.onrender.com/

From a Mind Map to a Working Tool: What Does a Code Assist Need?

I drew a mind map one afternoon in 2023. The question was simple: if you are building a code assist, what does it need ? Back then i ran out of ideas when i added the entire file into a context window, I needed a smart solution.

Try my product on your repo to look under the hood : https://grasprepo.onrender.com/

I went back to basics on how I would develop. when I used to assigned a “new feature request” early in my career. I used to do a series of items such as branching out a feature branch, learning the Domain knowledge, Coding guidelines, documenting & writing pseudo code, generating architecture docs, Bug fixes, Non-functional enhancements, Unit tests, integration tests, block box tests. Design documents prior to development phase and some histroy through Git history to understand the context. Use the Code formatters and linters defined for the project.

Drawing from my development experience(Domain) and the AI projects such as coding assist and code review buddy. I looked at what I drew, one thing became clear is that a code assist is not one tool. It is a compound product.

The Question Before the Code

Most code assist tools today focus on code generation. You type a prompt, you get code back. This part gets all the attention.

But back then in 2023–24 there was Devin and a few coming up. I kept wondering: what happens before you write a single line? You need to understand the codebase. You need to know which files matter, which ones are fragile, which ones will break if you touch them. You need to know the history. Who changed what, when, and why.

Nobody demos this part at conferences. But every developer who has inherited a legacy project knows this is where the real time goes.

I spent nearly 20 years in this industry. I have stared at repos wondering where to start more times than I want to admit. Every time the repo structure is different but my ritual is the same. Open the project, Scroll through files create entity relationship in mind. Read some recent git logs.Over days/weeks I slowly build a mental model.

The curiosity kept nagging me. If git already records everything about how a codebase changes, why are we still guessing? Back in 2019, I created a OSS project to tell a story based on git history. Just as any evolution a git repo carries a story in itself. I presented my idea in one of the conferences.

The Signal Is Already There

Git knows a lot about your code. It knows which files change the most. It knows how many people touched a file. It knows where the churn is. The structural relationships are in the code itself, in function definitions and references.

All of it is signal. Most developers ignore it because it is buried.

So I built grasprepo to pull this signal out. I wanted to see what the data would tell me.

What grasprepo Does

grasprepo is a Python toolkit with two components. Each one tackles a different dimension of the problem.

findchurn analyzes version control history. Point it at a repository with a filename and time window. It tells you: how many commits, how many contributors, how much code was added and removed. A file with 200 commits in three months by eight different developers is structurally different from a file with five stable commits by one developer. findchurn makes the difference visible.

repomap goes deeper. It parses source files using tree-sitter to extract every function definition and reference across the entire codebase. Then it builds a directed graph of file dependencies. File A references a function defined in File B, so there is an edge from A to B. Then it runs PageRank on the graph.

PageRank. The same algorithm Google used for web search. Applied to your codebase. I was curious what would happen, and the results were worth the experiment.

A file defining a function used everywhere is a load-bearing wall. A file referencing many things but defining little is a leaf node, safe to refactor independently. PageRank quantifies this intuition and gives you a number.

Connecting the Mind Map to the Tool

Go back to my mind map. Look at the branches.

Git history and context. This is findchurn. It surfaces which files are active, volatile, touched by many hands.

Coding guidelines and documentation. When you know which files are central (high PageRank) and which are changing constantly (high churn), you know where to focus your documentation effort. You know which files need better guidelines because they are the ones everyone touches.

Files with high churn and high contributor count often contain poorly understood code, getting patched repeatedly. findchurn identifies these files. They are your best candidates for targeted refactoring.

Design documents are developed prior to development. Before making architectural changes, run repomap to see the cascading effects. A change looking isolated might affect dozens of downstream files. Understanding this before you start prevents nasty surprises mid-refactor.

The mind map had ten branches. grasprepo addresses three or four of them. This is the honest truth. A code assist needs domain knowledge, it needs test generation, it needs formatting. grasprepo does none of those things. It does codebase understanding through data. And it does this part well.

The Prioritization Matrix

When you combine churn data with structural importance, you get a risk-weighted prioritization.

High churn and high PageRank: highest risk refactoring target. The file is both fragile and consequential. Handle with care.

High churn but low PageRank: fragile but isolated. Refactor freely, the blast radius is small.

Low churn but high PageRank: stable and central. Leave it alone unless you have a strong reason.

Low churn and low PageRank: safe territory. Good place for new team members to start.

Four quadrants. Each tells you something specific about where to spend your time.

What I Learned Building This

Code churn is an underrated metric. Files changing frequently with many contributors are almost always where the bugs live.

Once you treat a codebase as a graph, new questions appear. What is the most central file? What would break if I changed this function? Which files are isolated and safe to modify? Are there circular dependencies creating hidden coupling? Each question led me to the next one.

You do not need a perfect tool to get value, grasprepo is rough but it answers questions taking me hours of manual investigation before. Each developer tool such as cursor, Windsurf, claudecode should have something like grasprepo as its core USP driving their tool. If you are a curious person who wants to understand how does the magic happens then this is for you.

This Curiosity Is Not New

grasprepo is not my first attempt at this problem. Five years ago, I built Smart-Review: https://medium.com/towardsdev/are-you-adding-the-best-code-reviewer-for-each-pull-request-59706275acc7 .

The question back then was different but came from the same place: who is the right person to review a pull request?

The industry answer was static, Your lead, Your manager. But I kept asking: what about the engineer who wrote the module you are modifying? What about the person who has the most history with the code?

Smart-Review used PyDriller to mine git history and dynamically recommend reviewers based on who had real hands-on experience with the changed files, Not hierarchy, Not seniority. Data.

I open sourced it at github.com/pitchdarkdata/MVP1. It was rough. But the core idea was sound: git history tells you who knows the code. Use it.

In 2023, grasprepo asks a related question. Smart-Review asked “who should review this?” grasprepo asks “what should I focus on?” Same data source, Same curiosity, Different angle. Please note these were developed before vibe coding era where we have to spend time to understand and this helped me to create these tools.

What I Learned Opening Other People Codebases

The part nobody talks to you about. whenever you Contributed to open source is not writing code. It is understanding code. It is building the map in your head before you change a single line.

And this is exactly what my mind map was about. The ten branches of a code assist are the ten things I needed every time I opened a large codebase.

The Shoulders I Stood On

PyDriller gives you the ability to treat git history as a queryable dataset. I have been building on it for five years now, from Smart-Review to grasprepo. Instead of parsing log output with fragile regexes, you ask structured questions directly.

Aider inspired the context-building approach. The way Aider figures out which files are relevant to a coding task, by building a map of definitions, references, and relationships, was exactly the thinking I wanted.

When you are curious about a problem, other people’s tools start looking like answers to your own questions.

Try It

Both tools are open source.

grasprepo: github.com/brettleehari/grasprepo (churn analysis + structural mapping) Smart-Review (MVP1): github.com/pitchdarkdata/MVP1 (dynamic reviewer recommendation)

I started with a mind map of ten branches. I built tools covering three or four. I contributed to other people’s tools to fill in a few more. There is always room for improvement.

If you have ideas for the remaining branches, or if you use

https://grasprepo.onrender.com/

grasprepo on your own codebase and find something interesting, I want to hear about it.

The answers about your code are already in your git history and your source files. Your code agent need to get curious enough to look at this detail