nilaway

README

NilAway

[!WARNING]
NilAway is currently under active development: false positives and breaking changes can happen. We highly appreciate any feedback and contributions!

NilAway is a static analysis tool that seeks to help developers avoid nil panics in production by catching them at compile time rather than runtime. NilAway is similar to the standard nilness analyzer, however, it employs much more sophisticated and powerful static analysis techniques to track nil flows within a package as well across packages, and report errors providing users with the nilness flows for easier debugging.

NilAway enjoys three key properties that make it stand out:

• It is fully-automated: NilAway is equipped with an inference engine, making it require no any additional information from the developers (e.g., annotations) besides standard Go code.

• It is fast: we have designed NilAway to be fast and scalable, making it suitable for large codebases. In our measurements, we have observed less than 5% build-time overhead when NilAway is enabled. We are also constantly applying optimizations to further reduce its footprint.

• It is practical: it does not prevent all possible nil panics in your code, but it catches most of the potential nil panics we have observed in production, allowing NilAway to maintain a good balance between usefulness and build-time overhead.

🌟 For more detailed technical discussion, please check our Wiki, Engineering Blog, and paper (WIP).

Running NilAway

NilAway is implemented using the standard go/analysis, making it easy to integrate with existing analyzer drivers (i.e., golangci-lint, nogo, or running as a standalone checker).

[!IMPORTANT]
Due to the sophistication of the analyses that NilAway does, NilAway caches its findings about a particular package via the Fact Mechanism from the go/analysis framework. Therefore, it is highly recommended to leverage a driver that supports modular analysis (i.e., bazel/nogo or golangci-lint, but not the standalone checker since it stores all facts in memory) for better performance on large projects. For example, see instructions below for running NilAway on your project with bazel/nogo.

[!IMPORTANT]
By default, NilAway analyzes all Go code, including the standard libraries and dependencies. This helps NilAway better understand the code form dependencies and reduce its false negatives. However, this would also incur a significant performance cost (only once for drivers with modular support) and increase the number of non-actionable errors in dependencies, for large Go projects with a lot of dependencies.

We highly recommend using the include-pkgs flag to narrow down the analysis to your project's code exclusively. This directs NilAway to skip analyzing dependencies (e.g., third-party libraries), allowing you to focus solely on potential nil panics reported by NilAway in your first-party code!

Standalone Checker

Install the binary from source by running:

go install github.com/ZhongsJie/nilaway/cmd/nilaway@latest

Then, run the linter by:

nilaway -include-pkgs="<YOUR_PKG_PREFIX>,<YOUR_PKG_PREFIX_2>" ./...

Bazel/nogo

Running with bazel/nogo requires slightly more efforts. First follow the instructions from rules_go, gazelle, and nogo to set up your Go project such that it can be built with bazel/nogo with no or default set of linters configured. Then,

(1) Add import _ "github.com/ZhongsJie/nilaway" to your tools.go file (or other file that you use for configuring tool dependencies, see How can I track tool dependencies for a module? from Go Modules documentation) to avoid go mod tidy from removing NilAway as a tool dependency.

(2) Run the following commands to add NilAway as a tool dependency to your project:

# Get NilAway as a dependency, as well as getting its transitive dependencies in go.mod file.
$ go get github.com/ZhongsJie/nilaway@latest
# This should not remove NilAway as a dependency in your go.mod file.
$ go mod tidy
# Run gazelle to sync dependencies from go.mod to WORKSPACE file.
$ bazel run //:gazelle -- update-repos -from_file=go.mod

(3) Add NilAway to nogo configurations (usually in top-level BUILD.bazel file):

nogo(
    name = "my_nogo",
    visibility = ["//visibility:public"],  # must have public visibility
    deps = [
+++     "@org_uber_go_nilaway//:go_default_library",
    ],
    config = "config.json",
)

(4) Run bazel build to see NilAway working (any nogo error will stop the bazel build, you can use the --keep_going flag to request bazel to build as much as possible):

$ bazel build --keep_going //...

(5) See nogo documentation on how to pass a configuration JSON to the nogo driver, and see our wiki page on how to pass configurations to NilAway.

golangci-lint

NilAway, as its current form, still reports a fair number of false positives. This makes NilAway fail to be merged with golangci-lint and be offered as a linter (see PR#4045). The alternatives are to:

(1) build NilAway as a plugin to golangci-lint: the Go plugin system requires that NilAway shares the exact same versions of dependencies as the ones from golangci-lint. This is almost impossible for us to maintain.

(2) fork golangci-lint and add NilAway: it would also require us to keep in sync with upstream and cause unnecessary confusions to the users.

🙋 We would love to integrate NilAway with golangci-lint! If you have any other ideas here, please raise an issue (or better, a PR)!

Code Examples

Let's look at a few examples to see how NilAway can help prevent nil panics.

// Example 1:
var p *P
if someCondition {
      p = &P{}
}
print(p.f) // nilness reports NO error here, but NilAway does.

In this example, the local variable p is only initialized when someCondition is true. At the field access p.f, a panic may occur if someCondition is false. NilAway is able to catch this potential nil flow and reports the following error showing this nilness flow:

go.uber.org/example.go:12:9: error: Potential nil panic detected. Observed nil flow from source to dereference point:
    - go.uber.org/example.go:12:9: unassigned variable `p` accessed field `f`

If we guard this dereference with a nilness check (if p != nil), the error goes away.

NilAway is also able to catch nil flows across functions. For example, consider the following code snippet:

// Example 2:
func foo() *int {
      return nil
}
func bar() {
     print(*foo()) // nilness reports NO error here, but NilAway does.
}

In this example, the function foo returns a nil pointer, which is directly dereferenced in bar, resulting in a panic whenever bar is called. NilAway is able to catch this potential nil flow and reports the following error, describing the nilness flow across function boundaries:

go.uber.org/example.go:23:13: error: Potential nil panic detected. Observed nil flow from source to dereference point:
    - go.uber.org/example.go:20:14: literal `nil` returned from `foo()` in position 0
    - go.uber.org/example.go:23:13: result 0 of `foo()` dereferenced

Note that in the above example, foo does not necessarily have to reside in the same package as bar. NilAway is able to track nil flows across packages as well. Moreover, NilAway handles Go-specific language constructs such as receivers, interfaces, type assertions, type switches, and more.

Configurations

We expose a set of flags via the standard flag passing mechanism in go/analysis. Please check wiki/Configuration to see the available flags and how to pass them using different linter drivers.

Support

We follow the same version support policy as the Go project: we support and test the last two major versions of Go.

Please feel free to open a GitHub issue if you have any questions, bug reports, and feature requests.

Contributions

We'd love for you to contribute to NilAway! Please note that once you create a pull request, you will be asked to sign our Uber Contributor License Agreement.

License

This project is copyright 2023 Uber Technologies, Inc., and licensed under Apache 2.0.

Documentation

Overview

Package nilaway implements the top-level analyzer that simply retrieves the diagnostics from the accumulation analyzer and reports them.

Index

• Variables

Variables

var Analyzer = &analysis.Analyzer{
	Name:      "nilaway",
	Doc:       _doc,
	Run:       run,
	FactTypes: []analysis.Fact{},
	Requires:  []*analysis.Analyzer{config.Analyzer, accumulation.Analyzer},
}

Analyzer is the top-level instance of Analyzer - it coordinates the entire dataflow to report nil flow errors in this package. It is needed here for nogo to recognize the package.