CLI handling of named .go files and directories inconsistent with documentation

[gnattishness]

Welcome

• Yes, I'm using a binary release within 2 latest major releases. Only such installations are supported.
• Yes, I've searched similar issues on GitHub and didn't find any.
• Yes, I've included all information below (version, config, etc).
• Yes, I've tried with the standalone linter if available. (https://golangci-lint.run/usage/linters/)

Description of the problem

Similar had been previously reported in #942 and #1081, which had been automatically closed without being addressed.

The current Quick Start documentation presents the following usage:

golangci-lint/docs/src/docs/usage/quick-start.mdx

Lines 17 to 21 in 213fb56

	You can choose which directories and files to analyze:
	```sh
	golangci-lint run dir1 dir2/... dir3/file1.go
	```

When run, current golangci-lint would fail with the following error:

ERRO Running error: context loading failed: failed to load packages: failed to load with go/packages: -: named files must be .go files: ./dir1 

A similar use-case of named .go files in different directories would similarly fail with:

$ golangci-lint run dir1/file1.go dir2/file2.go
ERRO [linters context] typechecking error: named files must all be in one directory; have dir1 and dir2 

I appreciate that this is a limitation of "go/packages", but the documentation inconsistency is misleading and leads to lost, productive time.

Solutions could involve either:

1. Update docs to remove the misleading example and clarify how golangci-lint should be used, or
2. Modify CLI path handling to allow for both named .go files and packages

And optionally

3. Add CLI and config parameters that are effectively the opposite or negation of skip-dirs and skip-files - where files are analyzed but issues are only reported if they match one of the whitelist regexp.
   They could be perhaps named something like report-dirs and report-files, or whitelist-dirs.
   (I'll add this as a separate feature request if it sounds desirable, and could be willing to provide a PR)

My use-case involves running a noisy configuration on only a subset of files in a project.
One could specify skip-dirs and skip-files that exclude all but the few relevant files, but this can be quite time consuming for larger code-bases, particularly if the target files are not limited to a single directory.

Version of golangci-lint

$ golangci-lint --version
golangci-lint has version 1.49.0 built from cc2d97f3 on 2022-08-24T10:24:37Z

(binary install)

Configuration file

Reproducible with no config file (default)

Go environment

$ go version && go env
go version go1.18.4 linux/amd64
GO111MODULE="on"
GOARCH="amd64"
GOBIN=""
GOCACHE="<home>/.cache/go-build"
GOENV="<home>/.config/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GOMODCACHE="<home>/.asdf/installs/golang/1.18.4/packages/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="<home>/.asdf/installs/golang/1.18.4/packages"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="<home>/.asdf/installs/golang/1.18.4/go"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="<home>/.asdf/installs/golang/1.18.4/go/pkg/tool/linux_amd64"
GOVCS=""
GOVERSION="go1.18.4"
GCCGO="gccgo"
GOAMD64="v1"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="<path_to_project>/go.mod"
GOWORK=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build3977590971=/tmp/go-build -gno-record-gcc-switches"

Verbose output of running

E.g. if running on a cloned golangci-lint repo

$ golangci-lint cache clean
$ golangci-lint run -v pkg/config/config.go pkg/printers/
INFO [config_reader] Config search paths: [./ <project_root>/golangci-lint/pkg/config <project_root>/golangci-lint/pkg <project_root>/golangci-lint <project_root> <home> /home /] 
INFO [config_reader] Used config file .golangci.yml 
INFO [lintersdb] Active 31 linters: [bodyclose depguard dogsled dupl errcheck exportloopref funlen gochecknoinits goconst gocritic gocyclo gofmt goimports gomnd goprintffuncname gosec gosimple govet ineffassign lll misspell nakedret noctx nolintlint staticcheck stylecheck typecheck unconvert unparam unused whitespace] 
INFO [loader] Go packages loading at mode 575 (deps|types_sizes|compiled_files|files|imports|name|exports_file) took 343.928738ms 
ERRO Running error: context loading failed: failed to load packages: failed to load with go/packages: -: named files must be .go files: ./pkg/printers/ 
INFO Memory: 6 samples, avg is 27.5MB, max is 27.6MB 
INFO Execution took 491.127914ms    

or

$ golangci-lint cache clean
$ golangci-lint run -v pkg/config/config.go pkg/printers/printer.go
INFO [config_reader] Config search paths: [./ <project_root>/golangci-lint/pkg/config <project_root>/golangci-lint/pkg <project_root>/golangci-lint <project_root> <home> /home /] 
INFO [config_reader] Used config file .golangci.yml 
INFO [lintersdb] Active 31 linters: [bodyclose depguard dogsled dupl errcheck exportloopref funlen gochecknoinits goconst gocritic gocyclo gofmt goimports gomnd goprintffuncname gosec gosimple govet ineffassign lll misspell nakedret noctx nolintlint staticcheck stylecheck typecheck unconvert unparam unused whitespace] 
INFO [loader] Go packages loading at mode 575 (exports_file|files|name|types_sizes|compiled_files|deps|imports) took 326.702526ms 
INFO [runner/filename_unadjuster] Pre-built 0 adjustments in 8.21µs 
ERRO [linters context] typechecking error: named files must all be in one directory; have pkg/config and pkg/printers 
INFO [linters context/goanalysis] analyzers took 1.925996ms with top 10 stages: fact_deprecated: 271.904µs, buildir: 139.895µs, SA4016: 47.573µs, S1000: 47.154µs, stdmethods: 45.176µs, assign: 35.33µs, composites: 35.221µs, nakedret: 34.28µs, SA3001: 31.839µs, SA5008: 31.686µs 
INFO [runner] processing took 3.55µs with stages: max_same_issues: 596ns, skip_dirs: 459ns, max_from_linter: 317ns, nolint: 268ns, skip_files: 213ns, filename_unadjuster: 175ns, exclude: 151ns, cgo: 150ns, source_code: 147ns, path_prettifier: 146ns, uniq_by_line: 142ns, autogenerated_exclude: 133ns, exclude-rules: 133ns, max_per_file_from_linter: 120ns, diff: 119ns, identifier_marker: 64ns, sort_results: 60ns, path_shortener: 59ns, severity-rules: 52ns, path_prefixer: 46ns 
INFO [runner] linters took 529.64836ms with stages: goanalysis_metalinter: 529.572076ms 
INFO File cache stats: 0 entries of total size 0B 
INFO Memory: 12 samples, avg is 39.8MB, max is 64.9MB 
INFO Execution took 1.005481702s  

Code example or link to a public repository

E.g. Easily reproducible when run on https://github.com/golangci/golangci-lint

[boring-cyborg]

Hey, thank you for opening your first Issue ! 🙂 If you would like to contribute we have a guide for contributors.

[ldez]

Hello,

I think the documentation is more a kind of reference instead of a real example, so yes the doc must be improved.

[gnattishness]

Thanks for your quick response and agreed, I think that's the easiest way to fix the misunderstandings.

Anything extra can count as a feature request.
I'd provide a docs PR myself but I'm not confident in my understanding of how the CLI is intended to work.

e.g. whether linting a standalone .go file is always the same as targeting the whole package and skipping other files:

$ golangci-lint run -v pkg/printers/printer.go

$ golangci-lint run -v --skip-files '.*/[^p].*\.go' pkg/printers/

My guess is that the latter could identify issues with how the file integrates with other parts of the package, but I'm not familiar with golangci-lint's internals to confirm.