Static Analysis and Tooling

Relevant source files

• src/cmd/compile/internal/types2/assignments.go
• src/cmd/compile/internal/types2/builtins.go
• src/cmd/compile/internal/types2/call.go
• src/cmd/compile/internal/types2/compilersupport.go
• src/cmd/compile/internal/types2/decl.go
• src/cmd/compile/internal/types2/expr.go
• src/cmd/compile/internal/types2/index.go
• src/cmd/compile/internal/types2/literals.go
• src/cmd/compile/internal/types2/stmt.go
• src/cmd/compile/internal/types2/typexpr.go
• src/go/types/assignments.go
• src/go/types/builtins.go
• src/go/types/call.go
• src/go/types/decl.go
• src/go/types/expr.go
• src/go/types/index.go
• src/go/types/literals.go
• src/go/types/stmt.go
• src/go/types/typexpr.go
• src/internal/goexperiment/exp_newinliner_off.go
• src/internal/goexperiment/exp_newinliner_on.go
• src/internal/types/testdata/spec/range.go
• src/internal/types/testdata/spec/range_int.go

Purpose and Scope

This page describes the standard library packages used for static analysis and tooling in Go, primarily the go/types package which provides semantic analysis and type checking capabilities. These packages enable the creation of tools like gopls (language server), staticcheck (linter), and other analysis tools that reason about Go code.

For information about the compiler's internal type checking, see 3.1 Frontend and Type Checking. For runtime profiling and metrics, see 2.5 Runtime Metrics and Profiling.

Type Checking Architecture

The Go standard library provides two parallel type checking implementations:

Package	Purpose	Users
go/types	External type checker	Tools like gopls, staticcheck, IDE integrations
cmd/compile/internal/types2	Compiler type checker	Go compiler (cmd/compile) only

Both implementations share the same algorithms and most code structure, but go/types uses go/ast for parsing while types2 uses cmd/compile/internal/syntax.

Type Checking Pipeline

Sources: src/go/types/expr.go17-57 src/go/types/call.go1-15 src/go/types/decl.go1-14

The Checker Type

The Checker type is the central component of the type checking system. It maintains state during type checking and coordinates all checking operations.

Key Checker Components

Sources: src/go/types/expr.go17-57 src/go/types/decl.go48-167

Expression Type Checking

Expression checking is the core of semantic analysis. The algorithm processes expressions recursively from top to bottom.

Expression Checking Algorithm

From src/go/types/expr.go17-57:

1. Recursive descent: Expressions are checked top-down via rawExpr
2. Result representation: Each expression evaluation produces an operand with:
   • mode: The kind of value (constant, variable, value, typexpr, etc.)
   • typ: The type of the expression
   • val: The constant value (if mode is constant_)
3. Untyped tracking: Untyped expressions are recorded in check.untyped map
4. Type propagation: updateExprType propagates final types down the expression tree

Expression Checking Components

Sources: src/go/types/expr.go966-1200 src/go/types/call.go172-351

Operand Modes

The operand type represents expression evaluation results with different modes:

Mode	Description	Example
invalid	Type checking error occurred	Any invalid expression
novalue	Statement with no value	close(ch)
constant_	Compile-time constant	42, "hello"
typexpr	Type expression	int, []string
variable	Addressable value	Variable, field selection
value	Non-addressable value	Function call result
commaok	Expression with optional 2nd value	v, ok := m[key]
builtin	Built-in function reference	len, append

Sources: src/go/types/expr.go17-57 src/go/types/operand.go

Call and Function Instantiation

Call expression checking handles both ordinary function calls and generic function instantiation.

Function Call Type Checking

Sources: src/go/types/call.go172-351 src/go/types/call.go34-130 src/go/types/call.go463-673

Type Inference for Generics

When calling generic functions, the type checker performs type inference to determine type arguments:

1. Explicit type arguments: Provided in brackets f<FileRef file-url="https://github.com/golang/go/blob/0bf3f64c/int, string" undefined file-path="int, string">Hii</FileRef>
2. Partial inference: Some type arguments provided, others inferred
3. Full inference: All type arguments inferred from argument types (Go 1.21+)

From src/go/types/call.go70-122 the inference algorithm:

• Creates synthetic generic function g<FileRef file-url="https://github.com/golang/go/blob/0bf3f64c/type_parameters_of_x" undefined file-path="type_parameters_of_x">Hii</FileRef> for assignment contexts
• Renames type parameters to avoid recursive instantiation conflicts
• Uses check.infer() to solve type parameter constraints
• Instantiates the function signature with inferred types

Sources: src/go/types/call.go34-130 src/go/types/call.go463-673

Declaration Checking

Declaration checking resolves object types and detects invalid cycles.

Object Declaration States

From src/go/types/decl.go72-89 objects progress through three states during type checking:

State	Condition	Color Metaphor
Unknown	Not in objPathIdx, type == nil	White
Pending	In objPathIdx	Grey
Known	Not in objPathIdx, type != nil	Black

Declaration Cycle Detection

Sources: src/go/types/decl.go48-167 src/go/types/decl.go169-251

Valid Cycles

From src/go/types/decl.go169-251 valid cycles include:

• Cycles through type parameter lists (Go 1.18+)
• Cycles involving only constants/variables (handled by initialization order checking)
• Cycles with at least one type definition (prevents infinite alias expansion)

Sources: src/go/types/decl.go169-251 src/go/types/decl.go253-295

Built-in Function Checking

Built-in functions like len, append, make have special type checking rules implemented in src/go/types/builtins.go

Built-in Function Handling

Sources: src/go/types/builtins.go23-85 src/go/types/builtins.go86-148

Special Cases

Built-in functions have unique handling:

1. append: Special case for append([]byte, string...) - src/go/types/builtins.go96-148
2. len/cap: May be constants if applied to arrays without function calls - src/go/types/builtins.go149-231
3. make: Validates second/third arguments are integers - src/go/types/builtins.go521-616
4. copy: Validates both arguments have identical element types - src/go/types/builtins.go363-419

Sources: src/go/types/builtins.go23-85

The Info Type

The Info type collects type information during checking, making it available to tools.

Info Fields

Field	Type	Description
Types	map[ast.Expr]TypeAndValue	Type and value for each expression
Instances	map[*ast.Ident]Instance	Generic type/function instances
Defs	map[*ast.Ident]Object	Identifier definitions
Uses	map[*ast.Ident]Object	Identifier uses
Implicits	map[ast.Node]Object	Implicit objects (e.g., case clauses)
Selections	map[*ast.SelectorExpr]*Selection	Field/method selections
Scopes	map[ast.Node]*Scope	Scope for each node
InitOrder	[]*Initializer	Package-level initialization order

Tool Usage Pattern

Sources: src/go/types/api.go

Comparison: go/types vs types2

While both implementations share the same algorithms, they differ in usage:

Aspect	go/types	types2
AST Package	go/ast	cmd/compile/internal/syntax
Position Type	token.Pos	syntax.Pos
Public API	Yes	No (internal)
Used By	External tools	Compiler only
Code Location	src/go/types/	src/cmd/compile/internal/types2/
Generated From	types2 (with modifications)	Hand-written

The compiler uses types2 for tighter integration with its internal data structures, while external tools use the stable go/types API.

Sources: src/go/types/expr.go1-15 src/cmd/compile/internal/types2/expr.go1-15

Common Tool Patterns

Pattern 1: Basic Type Checking

Steps:
1. Parse files with parser.ParseFile()
2. Create types.Config with Importer
3. Create types.Info with desired output maps
4. Call config.Check() 
5. Access type information from Info

Pattern 2: Walking Definitions and Uses

Steps:
1. Populate Info.Defs and Info.Uses during checking
2. Iterate over Info.Defs to find all definitions
3. Iterate over Info.Uses to find all references
4. Use Object.Pos() for source locations

Pattern 3: Expression Type Analysis

Steps:
1. Populate Info.Types during checking
2. For each expression, lookup in Info.Types
3. Check TypeAndValue.Type for the expression's type
4. Check TypeAndValue.Value for constant values
5. Check TypeAndValue.IsValue()/IsType() for kind

Sources: src/go/types/api.go

Object Hierarchy

The type checker represents program entities as Object implementations:

Each Object has:

• Name(): The object's name
• Type(): The object's type
• Pos(): Source position
• Parent(): Containing scope
• Pkg(): Declaring package

Sources: src/go/types/object.go src/go/types/decl.go48-167

Scope Management

Scopes form a tree structure representing lexical nesting:

The Checker maintains the current scope and creates new scopes as it enters blocks, functions, and other lexical constructs via openScope() and closeScope().

Sources: src/go/types/scope.go src/cmd/compile/internal/types2/stmt.go156-164

Error Reporting

The type checker reports errors through the Config.Error callback. It distinguishes between:

1. Hard errors: Type errors that prevent compilation
2. Soft errors: Errors that may be ignored in some contexts (via check.softErrorf)

Error codes are defined in internal/types/errors and used consistently across both go/types and types2.

Sources: src/go/types/errors.go src/internal/types/errors/codes.go