Documentation
¶
Overview ¶
Package metrics enriches graph nodes with code health signals: cyclomatic complexity (computed during parsing), git churn, git blame, and test coverage.
Index ¶
- func BlameAgeLabel(dateStr string) string
- func EnrichBlame(g *graph.Graph, repoRoot string)
- func EnrichBlameForFile(g *graph.Graph, repoRoot, absFile string)
- func EnrichChurn(g *graph.Graph, repoRoot string, days int)
- func EnrichCommitContext(g *graph.Graph, repoRoot string)
- func EnrichCommitContextForFile(g *graph.Graph, repoRoot, absFile string)
- func EnrichCoverage(g *graph.Graph, repoRoot, profilePath string)
- func EnrichPprof(g *graph.Graph, repoRoot, profilePath string)
- func StalenessLabel(score float64) string
- type CommitInfo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BlameAgeLabel ¶
BlameAgeLabel converts an ISO short date ("2025-01-15") to a human-readable age relative to now ("3d ago", "1w ago", "2mo ago", "1y ago"). Returns "" if the date cannot be parsed.
func EnrichBlame ¶
EnrichBlame annotates every function/method node with git blame metadata: blame_author, blame_date, blame_commit, blame_subject, and staleness_score. Uses per-file granularity (one git log call per unique file) for performance. Nodes in vendored/generated paths are skipped. Must be called after EnrichChurn — staleness_score reads metadata["churn"]. Git errors are silently ignored; the graph remains usable without blame data.
func EnrichBlameForFile ¶
EnrichBlameForFile updates blame and churn metadata for all function/method nodes in a single file. Called by the watcher after a file is re-parsed to keep blame data current without a full re-blame of the entire graph. It is a no-op when git is unavailable, when the file has no commits, or when no function/method nodes exist in the file.
Unlike EnrichBlame (startup batch), this also computes per-file churn so that staleness_score is accurate even for nodes that were just created by an incremental reparse (which would otherwise have no churn metadata from the startup EnrichChurn scan).
func EnrichChurn ¶
EnrichChurn annotates every graph node with a "churn" metadata value indicating how many git commits touched the node's file in the last [days] days. Nodes in files with no recent commits are left unchanged. Errors (e.g. not a git repo) are silently ignored — the graph is still usable without churn data.
Supports umbrella workspaces where repoRoot is not itself a git repository but contains sub-repos (e.g. a monorepo with separate .git in each package). In that case, each file's git root is detected automatically.
func EnrichCommitContext ¶
EnrichCommitContext annotates every function/method node with the last 3 commit messages that touched its file. The subjects are stored as a JSON array in metadata["commit_context"] so they can be parsed and rendered at query time without a git subprocess.
Uses per-file granularity (one git log call per unique file, same as EnrichBlame) for performance. Nodes in vendored/generated paths are skipped. Git errors are silently ignored — the graph remains usable without commit data.
func EnrichCommitContextForFile ¶
EnrichCommitContextForFile updates commit context metadata for all function/method nodes in a single file. Called by the watcher after a file is re-parsed to keep commit data current without re-enriching the full graph. It is a no-op when git is unavailable, when the file has no commits, or when no function/method nodes exist in the file.
func EnrichCoverage ¶
EnrichCoverage parses a go test -coverprofile output file and annotates function/method nodes with a "coverage" metadata value (0.0–1.0, the fraction of statements covered by tests). Nodes without matching coverage data are left unchanged. Errors are silently ignored.
func EnrichPprof ¶
EnrichPprof parses a Go pprof CPU profile and annotates function/method nodes with metadata["cpu_pct"] — the flat CPU percentage contributed by that function. Uses `go tool pprof -top` (standard with every Go installation); errors are silently ignored so the graph remains usable without pprof data.
func StalenessLabel ¶
StalenessLabel converts a numeric staleness score to a qualitative label. low: < 30, medium: 30–149, high: ≥ 150.
Types ¶
type CommitInfo ¶
type CommitInfo struct {
Hash string `json:"hash"`
Author string `json:"author"`
Date string `json:"date"`
Message string `json:"message"`
// Body is the first 200 characters of the commit body (everything after the
// subject line). Empty when the commit has no body. Gives agents the "why"
// beyond the one-line subject — e.g. "Temporary workaround — revert before prod".
Body string `json:"body,omitempty"`
}
CommitInfo holds a summary of a single git commit, as surfaced by get_context's recent_changes field (R34: the "why" layer).
func RecentCommitsForFile ¶
func RecentCommitsForFile(ctx context.Context, repoRoot, filePath string, limit int) []CommitInfo
RecentCommitsForFile returns the last [limit] commits that touched filePath, using git log relative to repoRoot. Returns nil when not a git repo or when no commits exist for the file. Errors are silently swallowed — caller treats this as an optional enrichment.
Each CommitInfo includes Hash (short), Author, Date, Message (subject), and Body (first 200 chars of commit body, empty when none).
Source Files