structure

Documentation

Overview

Package structure derives a repository's topology — its subsystems and the dependencies between them — from language-agnostic, deterministic signals: the directory tree, dependency manifests, ownership and change history. It deliberately does NOT parse code. Symbol-level detail is a later, per-language drill-down; the top-down model is what humans actually navigate.

Index

• Constants
• func BuildSymbolMap(ctx context.Context, root string, opts MapOptions) (string, error)
• func EntityID(key string) string
• func PageRank(n int, refs map[int]map[int]float64, personal map[int]float64) []float64
• func ResolvePath(root, target string) (rel string, isPath bool)
• func SubsystemKey(id string) string
• type Dependency
• type ExternLister
• type ExternSymbol
• type MapOptions
• type Result
  • func Load(ctx context.Context, s store.Store) (Result, error)
  • func Scan(ctx context.Context, s store.Store, root string) (Result, error)
• type Subsystem
  • func ByHotness(subs []Subsystem) []Subsystem
  • func ContainingSubsystem(subs []Subsystem, rel string) (Subsystem, bool)
• type Symbol
• type SymbolGraph
  • func ExtractGoSymbols(ctx context.Context, root string, files []string) SymbolGraph

Constants

const (
	EcoNode   = "node"
	EcoGo     = "go"
	EcoRust   = "rust"
	EcoPython = "python"
	EcoJava   = "java"
)

Ecosystem labels the package manager / language family a subsystem belongs to. These abstractions are language-agnostic on purpose — a subsystem is a subsystem whether it's Go, Node, Rust, Python or Java.

Functions

func BuildSymbolMap

func BuildSymbolMap(ctx context.Context, root string, opts MapOptions) (string, error)

BuildSymbolMap builds the ranked symbol digest for the repo at root: Go via AST, TS/JS/Python via the injected LSP lister (absent language servers degrade to a note, never an error).

func EntityID

func EntityID(key string) string

EntityID returns the entity id for a subsystem key.

func PageRank

func PageRank(n int, refs map[int]map[int]float64, personal map[int]float64) []float64

PageRank returns one score per symbol. personal maps symbol index → EXTRA teleport weight, blended on top of a uniform base (p[i] ∝ 1 + personal[i]): seeds zoom the map without erasing the global structure — an exclusive teleport vector would rank a dirty scratch file above the repo's real hubs. Empty/nil personal = plain uniform PageRank.

func ResolvePath

func ResolvePath(root, target string) (rel string, isPath bool)

ResolvePath reports whether target names an existing path (relative to the working directory or the repo root) and returns its slash path relative to root. Shared by the context compiler and the provenance command.

func SubsystemKey

func SubsystemKey(id string) string

SubsystemKey strips the "subsystem:" prefix from an entity id.

Types

type Dependency

type Dependency struct {
	From string `json:"from"`
	To   string `json:"to"`
}

Dependency is a directed edge between two subsystems (by key).

type ExternLister

type ExternLister func(ctx context.Context, absPath string) ([]ExternSymbol, bool)

ExternLister returns a file's declarations, or ok=false when no server serves the file's language.

type ExternSymbol

type ExternSymbol struct {
	Name    string `json:"name"`
	Kind    int    `json:"kind"` // LSP SymbolKind
	Line    int    `json:"line"`
	EndLine int    `json:"end_line"`
	SelLine int    `json:"sel_line"`
	Depth   int    `json:"depth"`
}

ExternSymbol is one declaration reported by an external (LSP) lister.

type MapOptions

type MapOptions struct {
	Focus  []string     // paths or symbol names to center the map on (personalization seeds)
	Budget int          // token budget for the digest (0 = default)
	Store  store.Store  // optional: persists the extern (LSP) symbol cache
	Extern ExternLister // optional: TS/JS/Python declarations (LSP documentSymbol)
}

MapOptions steers one repo-map build.

type Result

type Result struct {
	Root        string       `json:"root"`
	GeneratedAt time.Time    `json:"generated_at"`
	Subsystems  []Subsystem  `json:"subsystems"`
	Deps        []Dependency `json:"dependencies"`
	Docs        []string     `json:"docs,omitempty"` // repo-level docs (README, CLAUDE.md, …)
}

Result is the topology produced by a scan.

func Load

func Load(ctx context.Context, s store.Store) (Result, error)

Load reconstructs the topology from the materialized projection (the subsystem entities and depends_on edges), plus repo-level metadata from the structural state snapshot. Read-only — it does not re-scan the filesystem.

func Scan

func Scan(ctx context.Context, s store.Store, root string) (Result, error)

Scan builds the topology for the repo at root, persists it (subsystem entities, depends_on edges, and the structural current_state for scope "repo") and returns it for display.

type Subsystem

type Subsystem struct {
	Key       string   `json:"key"`       // path relative to repo root
	Name      string   `json:"name"`      // human label (package name or dir name)
	Ecosystem string   `json:"ecosystem"` // node | go | rust | python | java
	Package   string   `json:"package,omitempty"`
	Manifest  string   `json:"manifest"`       // manifest filename
	Docs      []string `json:"docs,omitempty"` // doc files in this subsystem
	Commits   int      `json:"commits"`        // all-time commits touching this subsystem
	Recent    int      `json:"recent_commits"` // commits in the recent window
	// Churn-weighted hotspot signals over the recent window. Commit COUNT alone is
	// a weak "where's the work" proxy — many tiny commits in one area drown out
	// fewer, deeper changes elsewhere. Lines changed + active days capture depth
	// and sustained effort; Hotness blends them (normalized across subsystems).
	RecentChurn int      `json:"recent_churn,omitempty"` // added+deleted lines in the recent window
	RecentDays  int      `json:"recent_days,omitempty"`  // distinct days with a commit in the window
	Hotness     float64  `json:"hotness,omitempty"`      // blended recent-activity score (0..1)
	Owners      []string `json:"owners,omitempty"`
}

Subsystem is a bounded implementation unit (a Go module, an npm package, a Cargo crate, …) — the "where" of the system.

func ByHotness

func ByHotness(subs []Subsystem) []Subsystem

ByHotness returns a copy of subs ranked by recent-activity hotness (churn + commits + active days, last 30d), with all-time commits and key as stable tiebreakers. This is the canonical "where is the work now" ordering.

func ContainingSubsystem

func ContainingSubsystem(subs []Subsystem, rel string) (Subsystem, bool)

ContainingSubsystem returns the subsystem whose key is the longest prefix of rel (the most specific enclosing subsystem).

type Symbol

type Symbol struct {
	Name     string `json:"name"`           // bare identifier (methods too — matching is by name)
	Recv     string `json:"recv,omitempty"` // method receiver type, for display
	Kind     string `json:"kind"`           // func | method | type | const | var | class | …
	Lang     string `json:"lang"`           // go | ts | py — reference matching stays within a language group
	Path     string `json:"path"`           // file, relative to the repo root
	Line     int    `json:"line"`
	EndLine  int    `json:"end_line,omitempty"` // full-range end (extern symbols; enclosing-attribution)
	Decl     string `json:"decl"`               // the declaration's first source line, trimmed
	Exported bool   `json:"exported"`
}

Symbol is one top-level declaration (Go via AST; TS/JS/Python via LSP).

type SymbolGraph

type SymbolGraph struct {
	Symbols []Symbol
	// Refs[from][to] = reference count: the body of Symbols[from] mentions the
	// name of Symbols[to]. Name-collision targets split weight (see extractRefs).
	Refs map[int]map[int]float64
	// FileRefs counts references INTO each symbol from other files' top level
	// (var initializers etc.) — kept per-symbol, feeds in-degree display.
	InDeg []float64
}

SymbolGraph is the repo-wide symbol reference graph.

func ExtractGoSymbols

func ExtractGoSymbols(ctx context.Context, root string, files []string) SymbolGraph

ExtractGoSymbols parses every non-test Go file under root (repo-tracked, vendored trees dropped) and returns the symbol reference graph. Parse errors skip the file — a broken working-tree file must not break orientation.

Reference resolution exploits Go's visibility rules instead of guessing: a BARE identifier can only reference a symbol in the SAME package (dir), and a cross-package reference is always an import selector (pkg.Name) — resolved exactly via the module path from go.mod. Selectors on non-package values (x.Method()) can't be typed without a checker, so they match METHOD symbols by name repo-wide with the weight split across candidates.