Configuration

In this wiki page we first list the available flags and their meanings, and then show how the flags are passed using popular linter drivers.

Flags

Include Packages (include-pkgs)

Since v0.1.0

A comma-separated list of package prefixes to include for analysis.

By default all packages (including standard and 3rd party libraries) will be loaded by the driver and passed to the linters for analysis. This may not be desirable in practice: the errors reported on them cannot be fixed locally, and the overhead for analyzing them is pointless. Hence this flag can be set to include packages that have certain prefixes (e.g., go.uber.org), such that only first-party code is analyzed. If a package is excluded from analysis, default nilabilities will be assumed (e.g., functions will be assumed to always return nonnil pointers).

⚠️ Please note that even if a package is excluded from analysis, errors might still be reported on them if the nilness flows happens within the analyzed package, but it includes using a struct from the excluded package. For example, if the analyzed package constructs a struct from the excluded package, assigns a nil to a field, and then immediately dereferences the field. In this case, NilAway will report an error for this flow, but the location will be on the field (that resides in the excluded package). To only report errors on the desired packages, please use the error suppression mechanisms specified in the driver (golangci-lint, nogo).

Exclude Packages (exclude-pkgs)

Since v0.1.0

A comma-separated list of package prefixes to exclude for analysis. This takes precedence over include-pkgs.

Exclude Files By Docstrings (exclude-file-docstrings)

Since v0.1.0

A comma-separated list of strings to search for in a file's docstrings to exclude a file from analysis.

Passing Configurations

NilAway adopts the standard flag passing mechanism in the go/analysis framework. However, the multi-analyzer architecture of NilAway (see wiki/Architecture) makes it slightly difficult to pass flags to NilAway. If we simply set the Flags fields to the top-level nilaway.Analyzer, by the time it is executed, the sub-analyzers have already done the work, making the flags meaningless (i.e., it can no long alter their behaviors).

To address this problem, we have defined a separate "nilaway_config" analyzer which is only responsible for defining the Flags field and expose the configs through its return value. All other sub-analyzers will depend on the config.Analyzer and use the values there to execute different logic.

This inevitably makes the configurations for NilAway slightly confusing: you will have to pass flags to the separate "nilaway_config" analyzer, while any error suppressions must be set for the top-level "nilaway" analyzer (since it is the one that eventually reports the errors).

Standalone Checker

For better UX, we lift the flags from "nilaway_config" to the top-level standalone driver, so they can be just specified by

nilaway -flag1 <VALUE> -flag2 <VALUE> ./...

Since the standalone linter driver does not support error suppression, which may be required for some deployments (see Include Package for a detailed discussion), we add two more flags to this specific checker for such functionality:

-include-errors-in-files string
    	A comma-separated list of file prefixes to report errors, default is current working directory.
-exclude-errors-in-files string
    	A comma-separated list of file prefixes to exclude from error reporting. This takes precedence over include-errors-in-files.

nogo

TODO

golangci-lint

TODO