repomap

Documentation

Overview

Package repomap is the prompt-injection shim that produces a token-budgeted repository overview for hawk's context layer. It builds an import/refer graph over the source files in root, ranks the nodes with a PageRank pass, and renders the highest-ranked files (and their top symbols) as a compact text block capped at Options.Budget tokens.

Relationship to internal/intelligence/repomap

hawk ships a second package, internal/intelligence/repomap, that exposes a much larger surface: call graphs, search, quality signals, API scanning, incremental indexing, and so on. That package is the deep analysis engine. THIS package is intentionally narrow: one entry point (RepoMap), a single Graph type, a self-contained scan/rank/render pipeline, and a stdlib-only dependency surface. The two packages share no code; they merely share a name and a goal (a useful map of a repository). The deep package's doc.go spells this out from the other side of the boundary.

Callers that need more than a budgeted text block - symbol-level navigation, BM25 search, dead-code detection, OpenAPI export, etc. - should import internal/intelligence/repomap directly instead of extending this one.

Implementation notes

Go files are parsed with go/parser and go/ast; other languages fall back to a small regex extractor. Only the standard library is used. Files larger than 1 MiB, hidden directories, and a small set of well-known build/vendor trees are skipped during the scan. The PageRank pass uses the standard damped iteration with dangling-mass redistribution and exits early once the total node-to-node delta drops below 1e-9.

Index

• Constants
• func EstimateTokens(s string) int
• func RepoMap(root string, budget int) (string, error)
• type FileNode
• type Graph
  • func Build(root string) (*Graph, error)
  • func (g *Graph) Rank()
  • func (g *Graph) Render(opts Options) string
• type Options
• type Symbol

Constants

const (
	// DefaultBudget is the token budget used when Options.Budget <= 0.
	DefaultBudget = 1024
	// DefaultMaxSymbolsPerFile caps per-file symbol output by default.
	DefaultMaxSymbolsPerFile = 12
)

Functions

func EstimateTokens

func EstimateTokens(s string) int

EstimateTokens approximates the token count of s. It uses a simple, deterministic word/character heuristic (~4 chars per token, with a minimum of one token per whitespace-delimited field) that is adequate for budgeting and avoids any model-specific tokenizer dependency.

func RepoMap

func RepoMap(root string, budget int) (string, error)

RepoMap scans root, ranks files, and returns a compact map string within the given token budget. A budget <= 0 uses DefaultBudget.

This is the primary entry point requested by the context layer.

Types

type FileNode

type FileNode struct {
	Path    string   // path relative to the scanned root, slash-separated
	Lang    string   // detected language ("go", "python", ...)
	Symbols []Symbol // extracted symbols, in source order
	Imports []string // raw import/reference targets (module paths, file refs)
	Rank    float64  // PageRank score (filled in by Rank)
}

FileNode is a node in the repository graph.

type Graph

type Graph struct {
	// Nodes is keyed by relative path.
	Nodes map[string]*FileNode
	// contains filtered or unexported fields
}

Graph is the in-memory representation of a scanned repository.

func Build

func Build(root string) (*Graph, error)

Build scans root and returns the populated graph (without ranking).

func (*Graph) Rank

func (g *Graph) Rank()

Rank runs a PageRank-like pass over the graph, filling each node's Rank.

It uses the standard damped iteration with uniform teleportation. Nodes with no outgoing edges distribute their mass uniformly (dangling handling). The result is stable and deterministic.

func (*Graph) Render

func (g *Graph) Render(opts Options) string

Render produces the compact, token-budgeted map string. Files are listed in descending rank order; the most-referenced files (and their symbols) appear first and are most likely to survive truncation under a tight budget.

type Options

type Options struct {
	// Budget is the approximate maximum number of tokens the emitted map may
	// occupy. Values <= 0 fall back to DefaultBudget.
	Budget int
	// MaxSymbolsPerFile caps how many symbols are listed per file. Values <= 0
	// fall back to DefaultMaxSymbolsPerFile.
	MaxSymbolsPerFile int
	// ExportedOnly, when true, lists only exported/public symbols.
	ExportedOnly bool
}

Options configures a RepoMap build.

type Symbol

type Symbol struct {
	Name     string // declared identifier
	Kind     string // "func", "type", "const", "var", "method", etc.
	Exported bool   // true if the symbol is part of the file's public surface
}

Symbol is a top-level declaration extracted from a source file.