go-semver-audit

A production-ready CLI tool for analyzing breaking changes in Go dependency upgrades.

Why This Exists

Upgrading Go dependencies is risky. Your code might compile successfully after bumping a version, but runtime breaks or unexpected behavior can slip through. While Go's semantic versioning and module system help, they don't catch everything—especially when maintainers accidentally break compatibility or you're jumping multiple versions.

go-semver-audit performs static analysis to compare the public API surface of your current dependency version against a proposed upgrade, then checks which exported symbols your code actually uses. It produces a risk report highlighting potential breaking changes that affect your project.

Think of it as a safety net before you commit to that upgrade.

30-second start

• Install: go install github.com/devblac/go-semver-audit/cmd/go-semver-audit@latest
• Run once: go-semver-audit -upgrade github.com/pkg/errors@v0.9.1
• Read the text report (default). Use -json for CI or -strict to fail on warnings.

When to use it

• Before bumping a dependency (especially majors or multi-version jumps)
• When you need proof that an upgrade is safe for your code
• When a team asks “what will this break?” and you need a quick, actionable report

Features

• API Diff Analysis: Compares exported types, functions, methods, and interfaces between dependency versions
• Usage-Aware: Only reports breaking changes for APIs you actually use in your code
• Risk Reports: Clear, actionable output showing removed functions, changed signatures, modified interfaces
• Batch Mode: Analyze multiple dependency upgrades in one run
• Dead Dependency Detection: Optionally identify unused dependencies after upgrades
• CI-Friendly: JSON output mode and non-zero exit codes for automation
• Static Analysis Only: No code execution, no compilation of untrusted code

Installation

From Source

go install github.com/devblac/go-semver-audit/cmd/go-semver-audit@latest

Build Locally

git clone https://github.com/devblac/go-semver-audit.git
cd go-semver-audit
go build -o bin/go-semver-audit ./cmd/go-semver-audit

Usage

Basic Usage

Analyze a single dependency upgrade in the current directory:

go-semver-audit -upgrade github.com/gin-gonic/gin@v1.9.0

Specify Project Path

go-semver-audit -path ./myproject -upgrade github.com/pkg/errors@v0.9.1

JSON Output for CI

go-semver-audit -upgrade github.com/stretchr/testify@v1.8.0 -json

HTML Report for Sharing

go-semver-audit -upgrade github.com/gorilla/mux@v1.8.0 -html > audit.html

Strict Mode (Exit Non-Zero on Warnings)

go-semver-audit -upgrade golang.org/x/sync@v0.5.0 -strict

Detect Unused Dependencies

go-semver-audit -upgrade github.com/gorilla/mux@v1.8.0 -unused

CI Guardrail (copy-paste)

- uses: actions/setup-go@v5
  with:
    go-version: "1.22"
- name: Audit dependency upgrade
  env:
    MODULE: github.com/pkg/errors
    VERSION: v0.9.1
  run: go-semver-audit -upgrade ${MODULE}@${VERSION} -json -strict > semver-report.json
- uses: actions/upload-artifact@v4
  with:
    name: semver-report
    path: semver-report.json

Example Output

Analyzing upgrade: github.com/example/lib v1.2.0 -> v2.0.0

⚠️  BREAKING CHANGES DETECTED

Removed Functions:
  - lib.OldHelper (used in: main.go:45, utils/helper.go:12)
  
Changed Signatures:
  - lib.ParseConfig
    Old: func ParseConfig(path string) (*Config, error)
    New: func ParseConfig(path string, opts ...Option) (*Config, error)
    Used in: config/loader.go:23
  
Modified Interfaces:
  - lib.Handler
    Removed method: Handle(ctx context.Context) error
    Added method: HandleWithContext(ctx context.Context, meta Metadata) error
    Implementations found in: handlers/http.go:67

Summary: 3 breaking changes affecting 4 locations in your code.

Flags

Flag	Description	Default
-path	Path to Go project to analyze	. (current directory)
-upgrade	Dependency upgrade in format module@version	(required)
-json	Output results as JSON	false
-html	Output results as HTML	false
-strict	Exit non-zero on warnings (not just errors)	false
-unused	Report unused dependencies after upgrade	false
-v	Verbose output	false
-help	Show help message	-

How It Works

1. Parse Current State: Load your Go project and identify current dependency versions
2. Fetch Versions: Download/cache both old and new versions of the target dependency
3. Extract APIs: Parse exported symbols (types, functions, methods, interfaces) from both versions
4. Analyze Usage: Scan your codebase to find which exported symbols you actually import and use
5. Diff & Compare: Identify removed symbols, changed signatures, modified interfaces
6. Generate Report: Output only breaking changes that affect symbols you use

Limitations

This tool performs static analysis only and has inherent limitations:

• Cannot detect behavioral changes: If a function signature stays the same but behavior changes, we won't catch it
• Reflection blind spots: Dynamic calls via reflection may not be detected as usage
• Vendored dependencies: Analysis assumes standard module layout; vendored code may not be handled correctly
• CGO dependencies: Modules with cgo may not be fully analyzable
• Semantic compatibility: We detect API surface changes, not semantic versioning violations
• Build tags: May not analyze all conditional compilation branches
• Type aliases: Complex type aliasing chains may be oversimplified

This tool is a safety aid, not a guarantee. Always test your upgrades thoroughly.

Testing

The project includes comprehensive test coverage and continuous integration.

Running Tests Locally

# Run all tests
go test ./...

# Run tests with coverage
make test-coverage

# Run with race detector
go test -race ./...

See TESTING.md for detailed testing documentation.

Continuous Integration

CI runs automatically on all pull requests and pushes to main/develop branches:

• Tests across multiple OS (Linux, Windows, macOS) and Go versions (1.21, 1.22)
• Linting with go vet, gofmt, and staticcheck
• Coverage reporting via Codecov
• Build verification

Releases

• Tag a version: git tag v0.x.y && git push origin v0.x.y
• CI (GitHub Actions) builds cross-platform binaries via GoReleaser and publishes the GitHub Release
• Local dry run: goreleaser release --skip=publish --clean

Contributing

Contributions welcome! This project aims to stay minimal and focused.

Quick Start

# Clone the repository
git clone https://github.com/devblac/go-semver-audit.git
cd go-semver-audit

# Run tests
make test

# Run all checks (format, lint, test)
make check

Adding Features

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass and code is formatted (go fmt ./...)
5. Commit with clear messages (git commit -m 'Add detection for interface embedding')
6. Push and open a Pull Request

Code Style

• Follow Effective Go guidelines
• Keep functions small and focused
• Use table-driven tests
• Document exported functions and types
• Handle errors explicitly, no silent failures

Reporting Issues

Use GitHub Issues to report bugs or suggest features. Include:

• Go version (go version)
• Operating system
• Full command you ran
• Expected vs actual behavior
• Minimal reproduction example if possible

Related Tools

• golang.org/x/exp/apidiff: Experimental API diff tool (library-focused)
• go mod graph: Visualize dependency graphs
• nancy: Vulnerability scanner for Go dependencies

License

MIT License - see LICENSE file for details.

Acknowledgments

Built with golang.org/x/tools/go/packages for robust Go code analysis.