memguard

README

mem-guard

Static analysis for unbounded memory growth in Go programs.

mem-guard detects loop and recursion patterns that can grow data structures without bound — the kind of latent bugs that cause OOMs in production after weeks of uptime.

Install

go install github.com/ProfHercules/mem-guard/cmd/mem-guard@latest

Or download a pre-built binary from the releases page.

Usage

mem-guard ./...
mem-guard -json ./...
mem-guard -no-exit-code ./pkg/server

Exit codes: 0 clean, 1 error-severity findings, 2 usage or load failure.

Patterns detected

• AppendInLoop — append() inside an unbounded loop
• MapGrowInLoop — map writes inside an unbounded loop
• UnboundedConcat — string concatenation inside an unbounded loop
• GoroutineSpawnInLoop — go func() inside an unbounded loop
• RecursiveAccumulator — recursive function that grows a *[]T or map parameter
• CrossBoundaryGrowth — unbounded loop that calls a function which grows a passed-by-reference collection
• ChannelDrivenGrowth — collecting channel values into a growing data structure

A loop is considered unbounded unless it is provably bounded (counted for, range over a collection, or len()-bounded exit).

Library usage

import memguard "github.com/ProfHercules/mem-guard"

findings, err := memguard.Analyze([]string{"./..."}, memguard.Options{})
if err != nil {
    log.Fatal(err)
}
for _, f := range findings {
    fmt.Println(f)
}

License

MIT

Documentation

Overview

Package memguard detects unbounded memory growth patterns in Go programs.

It loads packages with golang.org/x/tools/go/packages, builds the SSA representation, and runs heuristics that flag append/map-grow/string-concat/ goroutine-spawn inside unbounded loops, recursive accumulators, cross-package growth via passed-by-reference collections, and channel-driven growth.

The library entry point is Analyze. The CLI lives at cmd/mem-guard.

Index

• Constants
• type Finding
  • func Analyze(patterns []string, opts Options) ([]Finding, error)
• type Heuristic
  • func DefaultHeuristics() []Heuristic
• type Options
• type Severity

Examples

• Analyze

Constants

const (
	SeverityInfo    = finding.SeverityInfo
	SeverityWarning = finding.SeverityWarning
	SeverityError   = finding.SeverityError
)

Types

type Finding

type Finding = finding.Finding

Re-exports so callers can use a single package import.

func Analyze

func Analyze(patterns []string, opts Options) ([]Finding, error)

Analyze loads the given Go package patterns and runs the configured heuristics. Findings are returned sorted (errors first, then file/line).

Example

package main

import (
	"fmt"

	memguard "github.com/ProfHercules/mem-guard"
)

func main() {
	findings, err := memguard.Analyze([]string{"./testdata/bounded"}, memguard.Options{})
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Println("findings:", len(findings))
}

Output:
findings: 0

type Heuristic

type Heuristic = heuristics.Heuristic

Re-exports so callers can use a single package import.

func DefaultHeuristics

func DefaultHeuristics() []Heuristic

DefaultHeuristics returns a fresh slice of the built-in heuristics.

type Options

type Options struct {
	// Dir is the working directory for package loading. Empty means cwd.
	Dir string
	// Heuristics overrides the built-in heuristic set. Nil means
	// DefaultHeuristics().
	Heuristics []Heuristic
}

Options controls an Analyze call.

type Severity

type Severity = finding.Severity

Re-exports so callers can use a single package import.