checklocks: fix panic on cross-package use of unexported global guards

[tigerquoll]

Problem

Any checklocks annotation whose guard is an unexported package-level variable panics the analyzer when the annotated function is called — or the annotated field is accessed — from a different package:

panic: interface conversion: interface is nil, not ssa.Value
    gvisor.dev/gvisor/tools/checklocks.(*globalGuard).resolveCommon(...)
        tools/checklocks/facts.go:208

Both resolution paths are affected — resolveCall (via checkFunctionCall) and resolveField (via checkGuards/checkFieldAccess). Minimal repro matrix (two packages: the guard-defining one and a caller):

guard	call annotation (+checklocksexclude: etc.)	field annotation (+checklocks:)
unexported global	panic	panic
exported global	works, enforces	works, enforces

Root cause

resolveCommon does pkg.Members[g.ObjectName].(ssa.Value) unchecked. For a cross-package use site, the guard package's SSA is created from export data, which does not include unexported package-level variables — the member lookup returns nil and the type assertion panics. (The interface-conversion, rather than nil-pointer, panic shows the package itself resolved; only the member is missing.)

History: #7721 (2022) fixed the exported cross-package case by adding the ImportedPackage lookup, but the tests it added only cover exported guards. The field-path variant of this panic has been latent since then; the call-path variant became commonly reachable when checklocksexclude{,write} landed (#12439).

Fix

Resolution now yields an explicitly unavailable resolvedValue when the guard object has no member in the resolving package, and the five use sites skip such guards instead of enforcing, reporting, or panicking. unavailable is deliberately distinct from the existing invalid state: invalid values are reported as "field %s cannot be resolved" in some paths and panic in lockState.isHeld/lockField in others, and neither is right here — the annotation itself is valid and remains fully enforced inside its defining package, so a use site that cannot materialize the object should be silent.

Skipping is sound: a consuming package could only hold the unresolvable guard via an acquire-annotated API whose fact references the same unresolvable object, so the acquisition could never enter its lock state either — the skipped check is vacuously unviolatable. This matches the analyzer's existing elision behavior (newly allocated objects, closures). In checkGuards, an unavailable guard is also excluded from guardsFound so it cannot silently relax a mixed +checkatomic field.

The README now documents the limitation in both places that list global locks as resolvable: an unexported global lock is enforceable only within its declaring package; export the lock if cross-package enforcement is required.

Tests

test/crosspkg + test/globals.go gain unexported-global-guard coverage for both paths, with +checklocksfail expectations verified load-bearing (removing them makes the analyzer report missing expected failure). Before the fix, the new tests reproduce the panic; after it, the analyzer's output over the whole test tree is otherwise identical to the pre-change baseline, and the exported cross-package cases still enforce.

Generated by the Author with assistance from Claude Code

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.