| 1 |
/* |
| 2 |
Copyright 2015 The Kubernetes Authors. |
| 3 |
|
| 4 |
Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 |
you may not use this file except in compliance with the License. |
| 6 |
You may obtain a copy of the License at |
| 7 |
|
| 8 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 9 |
|
| 10 |
Unless required by applicable law or agreed to in writing, software |
| 11 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 12 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 |
See the License for the specific language governing permissions and |
| 14 |
limitations under the License. |
| 15 |
*/ |
| 16 |
|
| 17 |
package parser |
| 18 |
|
| 19 |
import ( |
| 20 |
"errors" |
| 21 |
"fmt" |
| 22 |
"go/ast" |
| •23 |
"go/build" |
| 24 |
"go/constant" |
| 25 |
"go/token" |
| 26 |
gotypes "go/types" |
| 27 |
"path/filepath" |
| 28 |
"sort" |
| 29 |
"strings" |
| 30 |
"time" |
| 31 |
|
| 32 |
"golang.org/x/tools/go/packages" |
| 33 |
|
| 34 |
"k8s.io/gengo/v2/types" |
| 35 |
"k8s.io/klog/v2" |
| 36 |
) |
| 37 |
|
| 38 |
// Parser lets you add all the go files in all the packages that you care |
| 39 |
// about, then constructs the type source data. |
| 40 |
type Parser struct { |
| 41 |
// Map of package paths to definitions. These keys should be canonical |
| 42 |
// Go import paths (example.com/foo/bar) and not local paths (./foo/bar). |
| 43 |
goPkgs map[string]*packages.Package |
| 44 |
|
| 45 |
// Keep track of which packages were directly requested (as opposed to |
| 46 |
// those which are transitively loaded). |
| 47 |
userRequested map[string]bool |
| 48 |
|
| 49 |
// Keep track of which packages have already been scanned for types. |
| 50 |
fullyProcessed map[string]bool |
| 51 |
|
| 52 |
// Build tags to set when loading packages. |
| 53 |
buildTags []string |
| 54 |
|
| 55 |
// Tracks accumulated parsed files, so we can do position lookups later. |
| 56 |
fset *token.FileSet |
| 57 |
|
| 58 |
// All comments from everywhere in every parsed file. This map is keyed by |
| 59 |
// the file-line on which the comment block ends, which makes it easy to |
| 60 |
// look up comments which immediately precede a given obect (e.g. a type or |
| 61 |
// function definition), which is what we almost always want. We need this |
| 62 |
// because Go's own ast package does a very poor job of handling comments. |
| 63 |
endLineToCommentGroup map[fileLine]*ast.CommentGroup |
| 64 |
} |
| 65 |
|
| 66 |
// key type for finding comments. |
| 67 |
type fileLine struct { |
| 68 |
file string |
| 69 |
line int |
| 70 |
} |
| 71 |
|
| 72 |
// New constructs a new Parser. |
| 73 |
func New() *Parser { |
| 74 |
return NewWithOptions(Options{}) |
| 75 |
} |
| 76 |
|
| 77 |
func NewWithOptions(opts Options) *Parser { |
| 78 |
return &Parser{ |
| 79 |
goPkgs: map[string]*packages.Package{}, |
| 80 |
userRequested: map[string]bool{}, |
| 81 |
fullyProcessed: map[string]bool{}, |
| 82 |
fset: token.NewFileSet(), |
| 83 |
endLineToCommentGroup: map[fileLine]*ast.CommentGroup{}, |
| 84 |
buildTags: opts.BuildTags, |
| 85 |
} |
| 86 |
} |
| 87 |
|
| 88 |
// Options holds optional settings for the Parser. |
| 89 |
type Options struct { |
| 90 |
// BuildTags is a list of optional tags to be specified when loading |
| 91 |
// packages. |
| 92 |
BuildTags []string |
| 93 |
} |
| 94 |
|
| 95 |
// FindPackages expands the provided patterns into a list of Go import-paths, |
| 96 |
// much like `go list -find`. |
| 97 |
func (p *Parser) FindPackages(patterns ...string) ([]string, error) { |
| 98 |
return p.findPackages(nil, patterns...) |
| 99 |
} |
| 100 |
|
| 101 |
// baseCfg is an optional (may be nil) config which might be injected by tests. |
| 102 |
func (p *Parser) findPackages(baseCfg *packages.Config, patterns ...string) ([]string, error) { |
| 103 |
toFind := make([]string, 0, len(patterns)) |
| 104 |
results := make([]string, 0, len(patterns)) |
| 105 |
for _, pat := range patterns { |
| 106 |
if pkg := p.goPkgs[pat]; pkg != nil { |
| 107 |
results = append(results, pkg.PkgPath) |
| 108 |
} else { |
| 109 |
toFind = append(toFind, pat) |
| 110 |
} |
| 111 |
} |
| 112 |
if len(toFind) == 0 { |
| 113 |
return results, nil |
| 114 |
} |
| 115 |
|
| 116 |
cfg := packages.Config{ |
| 117 |
Mode: packages.NeedName | packages.NeedFiles, |
| 118 |
BuildFlags: []string{"-tags", strings.Join(p.buildTags, ",")}, |
| 119 |
Tests: false, |
| 120 |
} |
| 121 |
if baseCfg != nil { |
| 122 |
// This is to support tests, e.g. to inject a fake GOPATH or CWD. |
| 123 |
cfg.Dir = baseCfg.Dir |
| 124 |
cfg.Env = baseCfg.Env |
| 125 |
} |
| 126 |
|
| 127 |
pkgs, err := packages.Load(&cfg, toFind...) |
| 128 |
if err != nil { |
| 129 |
return nil, fmt.Errorf("error loading packages: %w", err) |
| 130 |
} |
| 131 |
var allErrs []error |
| 132 |
for _, pkg := range pkgs { |
| •133 |
pkgPath := pkg.PkgPath |
| 134 |
if pkgPath[0] == '_' && strings.HasPrefix(pkgPath[1:], build.Default.GOPATH) { |
| 135 |
// If GOPATH mode is used, the PkgPath returned by packages.Load |
| 136 |
// will be of the form "_<GOPATH>/src/<IMPORT_PATH>". We thus |
| 137 |
// reslice the string to only get the <IMPORT_PATH> part. |
| 138 |
pkgPath = pkg.PkgPath[len(build.Default.GOPATH)+6:] |
| 139 |
} |
| 140 |
results = append(results, pkgPath) |
| 141 |
|
| 142 |
// pkg.Errors is not a slice of `error`, but concrete types. We have |
| 143 |
// to iteratively convert each one into `error`. |
| 144 |
var errs []error |
| 145 |
for _, e := range pkg.Errors { |
| 146 |
errs = append(errs, e) |
| 147 |
} |
| 148 |
if len(errs) > 0 { |
| 149 |
allErrs = append(allErrs, fmt.Errorf("error(s) in %q:\n%w", pkg.PkgPath, errors.Join(errs...))) |
| 150 |
} |
| 151 |
} |
| 152 |
if len(allErrs) != 0 { |
| 153 |
return nil, errors.Join(allErrs...) |
| 154 |
} |
| 155 |
return results, nil |
| 156 |
} |
| 157 |
|
| 158 |
// LoadPackages loads and parses the specified Go packages. Specifically |
| 159 |
// named packages (without a trailing "/...") which do not exist or have no Go |
| 160 |
// files are an error. |
| 161 |
func (p *Parser) LoadPackages(patterns ...string) error { |
| 162 |
_, err := p.loadPackages(patterns...) |
| 163 |
return err |
| 164 |
} |
| 165 |
|
| 166 |
// LoadPackagesWithConfigForTesting loads and parses the specified Go packages with the |
| 167 |
// specified packages.Config as a starting point. This is for testing, and |
| 168 |
// only the .Dir and .Env fields of the Config will be considered. |
| 169 |
func (p *Parser) LoadPackagesWithConfigForTesting(cfg *packages.Config, patterns ...string) error { |
| 170 |
_, err := p.loadPackagesWithConfig(cfg, patterns...) |
| 171 |
return err |
| 172 |
} |
| 173 |
|
| 174 |
// LoadPackagesTo loads and parses the specified Go packages, and inserts them |
| 175 |
// into the specified Universe. It returns the packages which match the |
| 176 |
// patterns, but loads all packages and their imports, recursively, into the |
| 177 |
// universe. See NewUniverse for more. |
| 178 |
func (p *Parser) LoadPackagesTo(u *types.Universe, patterns ...string) ([]*types.Package, error) { |
| 179 |
// Load Packages. |
| 180 |
pkgs, err := p.loadPackages(patterns...) |
| 181 |
if err != nil { |
| 182 |
return nil, err |
| 183 |
} |
| 184 |
|
| 185 |
// Load types in all packages (it will internally filter). |
| 186 |
if err := p.addPkgsToUniverse(pkgs, u); err != nil { |
| 187 |
return nil, err |
| 188 |
} |
| 189 |
|
| 190 |
// Return the results as gengo types.Packages. |
| 191 |
ret := make([]*types.Package, 0, len(pkgs)) |
| 192 |
for _, pkg := range pkgs { |
| 193 |
ret = append(ret, u.Package(pkg.PkgPath)) |
| 194 |
} |
| 195 |
|
| 196 |
return ret, nil |
| 197 |
} |
| 198 |
|
| 199 |
func (p *Parser) loadPackages(patterns ...string) ([]*packages.Package, error) { |
| 200 |
return p.loadPackagesWithConfig(nil, patterns...) |
| 201 |
} |
| 202 |
|
| 203 |
// baseCfg is an optional (may be nil) config which might be injected by tests. |
| 204 |
func (p *Parser) loadPackagesWithConfig(baseCfg *packages.Config, patterns ...string) ([]*packages.Package, error) { |
| 205 |
klog.V(5).Infof("loadPackages %q", patterns) |
| 206 |
|
| 207 |
// Loading packages is slow - only do ones we know we have not already done |
| 208 |
// (e.g. if a tool calls LoadPackages itself). |
| 209 |
existingPkgs, netNewPkgs, err := p.alreadyLoaded(baseCfg, patterns...) |
| 210 |
if err != nil { |
| 211 |
return nil, err |
| 212 |
} |
| 213 |
if vlog := klog.V(5); vlog.Enabled() { |
| 214 |
if len(existingPkgs) > 0 { |
| 215 |
keys := make([]string, 0, len(existingPkgs)) |
| 216 |
for _, p := range existingPkgs { |
| 217 |
keys = append(keys, p.PkgPath) |
| 218 |
} |
| 219 |
vlog.Infof(" already have: %q", keys) |
| 220 |
} |
| 221 |
if len(netNewPkgs) > 0 { |
| 222 |
vlog.Infof(" to be loaded: %q", netNewPkgs) |
| 223 |
} |
| 224 |
} |
| 225 |
|
| 226 |
// If these were not user-requested before, they are now. |
| 227 |
for _, pkg := range existingPkgs { |
| 228 |
if !p.userRequested[pkg.PkgPath] { |
| 229 |
p.userRequested[pkg.PkgPath] = true |
| 230 |
} |
| 231 |
} |
| 232 |
for _, pkg := range netNewPkgs { |
| 233 |
if !p.userRequested[pkg] { |
| 234 |
p.userRequested[pkg] = true |
| 235 |
} |
| 236 |
} |
| 237 |
|
| 238 |
if len(netNewPkgs) == 0 { |
| 239 |
return existingPkgs, nil |
| 240 |
} |
| 241 |
|
| 242 |
cfg := packages.Config{ |
| 243 |
Mode: packages.NeedName | |
| 244 |
packages.NeedFiles | packages.NeedImports | packages.NeedDeps | |
| 245 |
packages.NeedModule | packages.NeedTypes | packages.NeedSyntax, |
| 246 |
BuildFlags: []string{"-tags", strings.Join(p.buildTags, ",")}, |
| 247 |
Fset: p.fset, |
| 248 |
Tests: false, |
| 249 |
} |
| 250 |
if baseCfg != nil { |
| 251 |
// This is to support tests, e.g. to inject a fake GOPATH or CWD. |
| 252 |
cfg.Dir = baseCfg.Dir |
| 253 |
cfg.Env = baseCfg.Env |
| 254 |
} |
| 255 |
|
| 256 |
tBefore := time.Now() |
| 257 |
pkgs, err := packages.Load(&cfg, netNewPkgs...) |
| 258 |
if err != nil { |
| 259 |
return nil, fmt.Errorf("error loading packages: %w", err) |
| 260 |
} |
| 261 |
klog.V(5).Infof(" loaded %d pkg(s) in %v", len(pkgs), time.Since(tBefore)) |
| 262 |
|
| 263 |
// Handle any errors. |
| 264 |
collectErrors := func(pkg *packages.Package) error { |
| 265 |
var errs []error |
| 266 |
for _, e := range pkg.Errors { |
| 267 |
if e.Kind == packages.ListError || e.Kind == packages.ParseError { |
| 268 |
errs = append(errs, e) |
| 269 |
} |
| 270 |
} |
| 271 |
if len(errs) > 0 { |
| 272 |
return fmt.Errorf("error(s) in %q:\n%w", pkg.PkgPath, errors.Join(errs...)) |
| 273 |
} |
| 274 |
return nil |
| 275 |
} |
| 276 |
if err := forEachPackageRecursive(pkgs, collectErrors); err != nil { |
| 277 |
return nil, err |
| 278 |
} |
| 279 |
|
| 280 |
// Finish integrating packages into our state. |
| 281 |
absorbPkg := func(pkg *packages.Package) error { |
| 282 |
p.goPkgs[pkg.PkgPath] = pkg |
| 283 |
|
| 284 |
for _, f := range pkg.Syntax { |
| 285 |
for _, c := range f.Comments { |
| 286 |
// We need to do this on _every_ pkg, not just user-requested |
| 287 |
// ones, because some generators look at tags in other |
| 288 |
// packages. |
| 289 |
// |
| 290 |
// TODO: It would be nice if we only did this on user-requested |
| 291 |
// packages. The problem is that we don't always know which |
| 292 |
// other packages will need this information, and even when we |
| 293 |
// do we may have already loaded the package (as a transitive |
| 294 |
// dep) and might have stored pointers into it. Doing a |
| 295 |
// thorough "reload" without invalidating all those pointers is |
| 296 |
// a problem for another day. |
| 297 |
position := p.fset.Position(c.End()) // Fset is synchronized |
| 298 |
p.endLineToCommentGroup[fileLine{position.Filename, position.Line}] = c |
| 299 |
} |
| 300 |
} |
| 301 |
|
| 302 |
return nil |
| 303 |
} |
| 304 |
if err := forEachPackageRecursive(pkgs, absorbPkg); err != nil { |
| 305 |
return nil, err |
| 306 |
} |
| 307 |
|
| 308 |
return append(existingPkgs, pkgs...), nil |
| 309 |
} |
| 310 |
|
| 311 |
// alreadyLoaded figures out which of the specified patterns have already been loaded |
| 312 |
// and which have not, and returns those respectively. |
| 313 |
// baseCfg is an optional (may be nil) config which might be injected by tests. |
| 314 |
func (p *Parser) alreadyLoaded(baseCfg *packages.Config, patterns ...string) ([]*packages.Package, []string, error) { |
| 315 |
existingPkgs := make([]*packages.Package, 0, len(patterns)) |
| 316 |
netNewPkgs := make([]string, 0, len(patterns)) |
| 317 |
|
| 318 |
// Expand and canonicalize the requested patterns. This should be fast. |
| 319 |
if pkgPaths, err := p.findPackages(baseCfg, patterns...); err != nil { |
| 320 |
return nil, nil, err |
| 321 |
} else { |
| 322 |
for _, pkgPath := range pkgPaths { |
| 323 |
if pkg := p.goPkgs[pkgPath]; pkg != nil { |
| 324 |
existingPkgs = append(existingPkgs, pkg) |
| 325 |
} else { |
| 326 |
netNewPkgs = append(netNewPkgs, pkgPath) |
| 327 |
} |
| 328 |
} |
| 329 |
} |
| 330 |
return existingPkgs, netNewPkgs, nil |
| 331 |
} |
| 332 |
|
| 333 |
// forEachPackageRecursive will run the provided function on all of the specified |
| 334 |
// packages, and on their imports recursively. Errors are accumulated and |
| 335 |
// returned as via errors.Join. |
| 336 |
func forEachPackageRecursive(pkgs []*packages.Package, fn func(pkg *packages.Package) error) error { |
| 337 |
seen := map[string]bool{} // PkgPaths we have already visited |
| 338 |
var errs []error |
| 339 |
for _, pkg := range pkgs { |
| 340 |
errs = append(errs, recursePackage(pkg, fn, seen)...) |
| 341 |
} |
| 342 |
if len(errs) > 0 { |
| 343 |
return errors.Join(errs...) |
| 344 |
} |
| 345 |
return nil |
| 346 |
} |
| 347 |
|
| 348 |
func recursePackage(pkg *packages.Package, fn func(pkg *packages.Package) error, seen map[string]bool) []error { |
| 349 |
if seen[pkg.PkgPath] { |
| 350 |
return nil |
| 351 |
} |
| 352 |
var errs []error |
| 353 |
seen[pkg.PkgPath] = true |
| 354 |
if err := fn(pkg); err != nil { |
| 355 |
errs = append(errs, err) |
| 356 |
} |
| 357 |
for _, imp := range pkg.Imports { |
| 358 |
errs = append(errs, recursePackage(imp, fn, seen)...) |
| 359 |
} |
| 360 |
return errs |
| 361 |
} |
| 362 |
|
| 363 |
// UserRequestedPackages fetches a list of the user-imported packages. |
| 364 |
func (p *Parser) UserRequestedPackages() []string { |
| 365 |
// Iterate packages in a predictable order. |
| 366 |
pkgPaths := make([]string, 0, len(p.userRequested)) |
| 367 |
for k := range p.userRequested { |
| 368 |
pkgPaths = append(pkgPaths, string(k)) |
| 369 |
} |
| 370 |
sort.Strings(pkgPaths) |
| 371 |
return pkgPaths |
| 372 |
} |
| 373 |
|
| 374 |
// NewUniverse finalizes the loaded packages, searches through them for types |
| 375 |
// and produces a new Universe. The returned Universe has one types.Package |
| 376 |
// entry for each Go package that has been loaded, including all of their |
| 377 |
// dependencies, recursively. It also has one entry, whose key is "", which |
| 378 |
// represents "builtin" types. |
| 379 |
func (p *Parser) NewUniverse() (types.Universe, error) { |
| 380 |
u := types.Universe{} |
| 381 |
|
| 382 |
pkgs := []*packages.Package{} |
| 383 |
for _, path := range p.UserRequestedPackages() { |
| 384 |
pkgs = append(pkgs, p.goPkgs[path]) |
| 385 |
} |
| 386 |
if err := p.addPkgsToUniverse(pkgs, &u); err != nil { |
| 387 |
return nil, err |
| 388 |
} |
| 389 |
|
| 390 |
return u, nil |
| 391 |
} |
| 392 |
|
| 393 |
// addCommentsToType takes any accumulated comment lines prior to obj and |
| 394 |
// attaches them to the type t. |
| 395 |
func (p *Parser) addCommentsToType(obj gotypes.Object, t *types.Type) { |
| 396 |
t.CommentLines = p.docComment(obj.Pos()) |
| 397 |
t.SecondClosestCommentLines = p.priorDetachedComment(obj.Pos()) |
| 398 |
} |
| 399 |
|
| 400 |
// packageDir tries to figure out the directory of the specified package. |
| 401 |
func packageDir(pkg *packages.Package) (string, error) { |
| 402 |
// Sometimes Module is present but has no Dir, e.g. when it is vendored. |
| 403 |
if pkg.Module != nil && pkg.Module.Dir != "" { |
| 404 |
// NOTE: this will not work if tests are loaded, because Go mutates the |
| 405 |
// Package.PkgPath. |
| 406 |
subdir := strings.TrimPrefix(pkg.PkgPath, pkg.Module.Path) |
| 407 |
return filepath.Join(pkg.Module.Dir, subdir), nil |
| 408 |
} |
| 409 |
if len(pkg.GoFiles) > 0 { |
| 410 |
return filepath.Dir(pkg.GoFiles[0]), nil |
| 411 |
} |
| 412 |
if len(pkg.IgnoredFiles) > 0 { |
| 413 |
return filepath.Dir(pkg.IgnoredFiles[0]), nil |
| 414 |
} |
| 415 |
return "", fmt.Errorf("can't find package dir for %q - no module info and no Go files", pkg.PkgPath) |
| 416 |
} |
| 417 |
|
| 418 |
// addPkgsToUniverse adds the packages, and all of their deps, recursively, to |
| 419 |
// the universe and (if needed) searches through them for types. |
| 420 |
func (p *Parser) addPkgsToUniverse(pkgs []*packages.Package, u *types.Universe) error { |
| 421 |
addOne := func(pkg *packages.Package) error { |
| 422 |
if err := p.addPkgToUniverse(pkg, u); err != nil { |
| 423 |
return err |
| 424 |
} |
| 425 |
return nil |
| 426 |
} |
| 427 |
if err := forEachPackageRecursive(pkgs, addOne); err != nil { |
| 428 |
return err |
| 429 |
} |
| 430 |
return nil |
| 431 |
} |
| 432 |
|
| 433 |
// addPkgToUniverse adds one package to the universe and (if needed) searches |
| 434 |
// through it for types. |
| 435 |
func (p *Parser) addPkgToUniverse(pkg *packages.Package, u *types.Universe) error { |
| 436 |
pkgPath := pkg.PkgPath |
| 437 |
if p.fullyProcessed[pkgPath] { |
| 438 |
return nil |
| 439 |
} |
| 440 |
|
| 441 |
// This will get-or-create the Package. |
| 442 |
gengoPkg := u.Package(pkgPath) |
| 443 |
|
| 444 |
if gengoPkg.Dir == "" { |
| 445 |
// We're keeping this package, though we might not fully process it. |
| 446 |
if vlog := klog.V(5); vlog.Enabled() { |
| 447 |
why := "user-requested" |
| 448 |
if !p.userRequested[pkgPath] { |
| 449 |
why = "dependency" |
| 450 |
} |
| 451 |
vlog.Infof("addPkgToUniverse %q (%s)", pkgPath, why) |
| 452 |
} |
| 453 |
|
| 454 |
absPath := "" |
| 455 |
if dir, err := packageDir(pkg); err != nil { |
| 456 |
return err |
| 457 |
} else { |
| 458 |
absPath = dir |
| 459 |
} |
| 460 |
|
| 461 |
gengoPkg.Path = pkg.PkgPath |
| 462 |
gengoPkg.Dir = absPath |
| 463 |
} |
| 464 |
|
| 465 |
// If the package was not user-requested, we can stop here. |
| 466 |
if !p.userRequested[pkgPath] { |
| 467 |
return nil |
| 468 |
} |
| 469 |
|
| 470 |
// Mark it as done, so we don't ever re-process it. |
| 471 |
p.fullyProcessed[pkgPath] = true |
| 472 |
gengoPkg.Name = pkg.Name |
| 473 |
|
| 474 |
// For historical reasons we treat files named "doc.go" specially. |
| 475 |
// TODO: It would be nice to not do this and instead treat package |
| 476 |
// doc-comments as the "global" config place. This would require changing |
| 477 |
// most generators and input files. |
| 478 |
for _, f := range pkg.Syntax { |
| 479 |
// This gets the filename for the ast.File. Iterating pkg.GoFiles is |
| 480 |
// documented as unreliable. |
| 481 |
pos := p.fset.Position(f.FileStart) |
| 482 |
if filepath.Base(pos.Filename) == "doc.go" { |
| 483 |
gengoPkg.Comments = []string{} |
| 484 |
for i := range f.Comments { |
| 485 |
gengoPkg.Comments = append(gengoPkg.Comments, splitLines(f.Comments[i].Text())...) |
| 486 |
} |
| 487 |
if f.Doc != nil { |
| 488 |
gengoPkg.DocComments = splitLines(f.Doc.Text()) |
| 489 |
} |
| 490 |
} |
| 491 |
} |
| 492 |
|
| 493 |
// Walk all the types, recursively and save them for later access. |
| 494 |
s := pkg.Types.Scope() |
| 495 |
for _, n := range s.Names() { |
| 496 |
switch obj := s.Lookup(n).(type) { |
| 497 |
case *gotypes.TypeName: |
| 498 |
t := p.walkType(*u, nil, obj.Type()) |
| 499 |
p.addCommentsToType(obj, t) |
| 500 |
case *gotypes.Func: |
| 501 |
// We only care about functions, not concrete/abstract methods. |
| 502 |
if obj.Type() != nil && obj.Type().(*gotypes.Signature).Recv() == nil { |
| 503 |
t := p.addFunction(*u, nil, obj) |
| 504 |
p.addCommentsToType(obj, t) |
| 505 |
} |
| 506 |
case *gotypes.Var: |
| 507 |
if !obj.IsField() { |
| 508 |
t := p.addVariable(*u, nil, obj) |
| 509 |
p.addCommentsToType(obj, t) |
| 510 |
} |
| 511 |
case *gotypes.Const: |
| 512 |
t := p.addConstant(*u, nil, obj) |
| 513 |
p.addCommentsToType(obj, t) |
| 514 |
default: |
| 515 |
klog.Infof("addPkgToUniverse %q: unhandled object of type %T: %v", pkgPath, obj, obj) |
| 516 |
} |
| 517 |
} |
| 518 |
|
| 519 |
// Add all of this package's imports. |
| 520 |
importedPkgs := []string{} |
| 521 |
for _, imp := range pkg.Imports { |
| 522 |
if err := p.addPkgToUniverse(imp, u); err != nil { |
| 523 |
return err |
| 524 |
} |
| 525 |
importedPkgs = append(importedPkgs, imp.PkgPath) |
| 526 |
} |
| 527 |
sort.Strings(importedPkgs) |
| 528 |
u.AddImports(pkg.PkgPath, importedPkgs...) |
| 529 |
|
| 530 |
return nil |
| 531 |
} |
| 532 |
|
| 533 |
// If the specified position has a "doc comment", return that. |
| 534 |
func (p *Parser) docComment(pos token.Pos) []string { |
| 535 |
// An object's doc comment always ends on the line before the object's own |
| 536 |
// declaration. |
| 537 |
c1 := p.priorCommentLines(pos, 1) |
| 538 |
return splitLines(c1.Text()) // safe even if c1 is nil |
| 539 |
} |
| 540 |
|
| 541 |
// If there is a detached (not immediately before a declaration) comment, |
| 542 |
// return that. |
| 543 |
func (p *Parser) priorDetachedComment(pos token.Pos) []string { |
| 544 |
// An object's doc comment always ends on the line before the object's own |
| 545 |
// declaration. |
| 546 |
c1 := p.priorCommentLines(pos, 1) |
| 547 |
|
| 548 |
// Using a literal "2" here is brittle in theory (it means literally 2 |
| 549 |
// lines), but in practice Go code is gofmt'ed (which elides repeated blank |
| 550 |
// lines), so it works. |
| 551 |
var c2 *ast.CommentGroup |
| 552 |
if c1 == nil { |
| 553 |
c2 = p.priorCommentLines(pos, 2) |
| 554 |
} else { |
| 555 |
c2 = p.priorCommentLines(c1.List[0].Slash, 2) |
| 556 |
} |
| 557 |
return splitLines(c2.Text()) // safe even if c1 is nil |
| 558 |
} |
| 559 |
|
| 560 |
// If there's a comment block which ends nlines before pos, return it. |
| 561 |
func (p *Parser) priorCommentLines(pos token.Pos, lines int) *ast.CommentGroup { |
| 562 |
position := p.fset.Position(pos) |
| 563 |
key := fileLine{position.Filename, position.Line - lines} |
| 564 |
return p.endLineToCommentGroup[key] |
| 565 |
} |
| 566 |
|
| 567 |
func splitLines(str string) []string { |
| 568 |
return strings.Split(strings.TrimRight(str, "\n"), "\n") |
| 569 |
} |
| 570 |
|
| 571 |
func goFuncNameToName(in string) types.Name { |
| 572 |
name := strings.TrimPrefix(in, "func ") |
| 573 |
nameParts := strings.Split(name, "(") |
| 574 |
return goNameToName(nameParts[0]) |
| 575 |
} |
| 576 |
|
| 577 |
func goVarNameToName(in string) types.Name { |
| 578 |
nameParts := strings.Split(in, " ") |
| 579 |
// nameParts[0] is "var". |
| 580 |
// nameParts[2:] is the type of the variable, we ignore it for now. |
| 581 |
return goNameToName(nameParts[1]) |
| 582 |
} |
| 583 |
|
| 584 |
// goNameToName converts a go name string to a gengo types.Name. |
| 585 |
// It operates solely on the string on a best effort basis. The name may be updated |
| 586 |
// in walkType for generics. |
| 587 |
func goNameToName(in string) types.Name { |
| 588 |
// Detect anonymous type names. (These may have '.' characters because |
| 589 |
// embedded types may have packages, so we detect them specially.) |
| 590 |
if strings.HasPrefix(in, "struct{") || |
| 591 |
strings.HasPrefix(in, "<-chan") || |
| 592 |
strings.HasPrefix(in, "chan<-") || |
| 593 |
strings.HasPrefix(in, "chan ") || |
| 594 |
strings.HasPrefix(in, "func(") || |
| 595 |
strings.HasPrefix(in, "func (") || |
| 596 |
strings.HasPrefix(in, "*") || |
| 597 |
strings.HasPrefix(in, "map[") || |
| 598 |
strings.HasPrefix(in, "[") { |
| 599 |
return types.Name{Name: in} |
| 600 |
} |
| 601 |
|
| 602 |
// There may be '.' characters within a generic. Temporarily remove |
| 603 |
// the generic. |
| 604 |
genericIndex := strings.IndexRune(in, '[') |
| 605 |
if genericIndex == -1 { |
| 606 |
genericIndex = len(in) |
| 607 |
} |
| 608 |
|
| 609 |
// Otherwise, if there are '.' characters present, the name has a |
| 610 |
// package path in front. |
| 611 |
nameParts := strings.Split(in[:genericIndex], ".") |
| 612 |
name := types.Name{Name: in} |
| 613 |
if n := len(nameParts); n >= 2 { |
| 614 |
// The final "." is the name of the type--previous ones must |
| 615 |
// have been in the package path. |
| 616 |
name.Package, name.Name = strings.Join(nameParts[:n-1], "."), nameParts[n-1] |
| 617 |
// Add back the generic component now that the package and type name have been separated. |
| 618 |
if genericIndex != len(in) { |
| 619 |
name.Name = name.Name + in[genericIndex:] |
| 620 |
} |
| 621 |
} |
| 622 |
return name |
| 623 |
} |
| 624 |
|
| 625 |
func (p *Parser) convertSignature(u types.Universe, t *gotypes.Signature) *types.Signature { |
| 626 |
signature := &types.Signature{} |
| 627 |
for i := 0; i < t.Params().Len(); i++ { |
| 628 |
signature.Parameters = append(signature.Parameters, &types.ParamResult{ |
| 629 |
Name: t.Params().At(i).Name(), |
| 630 |
Type: p.walkType(u, nil, t.Params().At(i).Type()), |
| 631 |
}) |
| 632 |
} |
| 633 |
for i := 0; i < t.Results().Len(); i++ { |
| 634 |
signature.Results = append(signature.Results, &types.ParamResult{ |
| 635 |
Name: t.Results().At(i).Name(), |
| 636 |
Type: p.walkType(u, nil, t.Results().At(i).Type()), |
| 637 |
}) |
| 638 |
} |
| 639 |
if r := t.Recv(); r != nil { |
| 640 |
signature.Receiver = p.walkType(u, nil, r.Type()) |
| 641 |
} |
| 642 |
signature.Variadic = t.Variadic() |
| 643 |
return signature |
| 644 |
} |
| 645 |
|
| 646 |
// walkType adds the type, and any necessary child types. |
| 647 |
func (p *Parser) walkType(u types.Universe, useName *types.Name, in gotypes.Type) *types.Type { |
| 648 |
// Most of the cases are underlying types of the named type. |
| 649 |
name := goNameToName(in.String()) |
| 650 |
if useName != nil { |
| 651 |
name = *useName |
| 652 |
} |
| 653 |
|
| 654 |
// Handle alias types conditionally on go1.22+. |
| 655 |
// Inline this once the minimum supported version is go1.22 |
| 656 |
if out := p.walkAliasType(u, in); out != nil { |
| 657 |
return out |
| 658 |
} |
| 659 |
|
| 660 |
switch t := in.(type) { |
| 661 |
case *gotypes.Struct: |
| 662 |
out := u.Type(name) |
| 663 |
out.GoType = in |
| 664 |
if out.Kind != types.Unknown { |
| 665 |
return out |
| 666 |
} |
| 667 |
out.Kind = types.Struct |
| 668 |
for i := 0; i < t.NumFields(); i++ { |
| 669 |
f := t.Field(i) |
| 670 |
m := types.Member{ |
| 671 |
Name: f.Name(), |
| 672 |
Embedded: f.Anonymous(), |
| 673 |
Tags: t.Tag(i), |
| 674 |
Type: p.walkType(u, nil, f.Type()), |
| 675 |
CommentLines: p.docComment(f.Pos()), |
| 676 |
} |
| 677 |
out.Members = append(out.Members, m) |
| 678 |
} |
| 679 |
return out |
| 680 |
case *gotypes.Map: |
| 681 |
out := u.Type(name) |
| 682 |
out.GoType = in |
| 683 |
if out.Kind != types.Unknown { |
| 684 |
return out |
| 685 |
} |
| 686 |
out.Kind = types.Map |
| 687 |
out.Elem = p.walkType(u, nil, t.Elem()) |
| 688 |
out.Key = p.walkType(u, nil, t.Key()) |
| 689 |
return out |
| 690 |
case *gotypes.Pointer: |
| 691 |
out := u.Type(name) |
| 692 |
out.GoType = in |
| 693 |
if out.Kind != types.Unknown { |
| 694 |
return out |
| 695 |
} |
| 696 |
out.Kind = types.Pointer |
| 697 |
out.Elem = p.walkType(u, nil, t.Elem()) |
| 698 |
return out |
| 699 |
case *gotypes.Slice: |
| 700 |
out := u.Type(name) |
| 701 |
out.GoType = in |
| 702 |
if out.Kind != types.Unknown { |
| 703 |
return out |
| 704 |
} |
| 705 |
out.Kind = types.Slice |
| 706 |
out.Elem = p.walkType(u, nil, t.Elem()) |
| 707 |
return out |
| 708 |
case *gotypes.Array: |
| 709 |
out := u.Type(name) |
| 710 |
out.GoType = in |
| 711 |
if out.Kind != types.Unknown { |
| 712 |
return out |
| 713 |
} |
| 714 |
out.Kind = types.Array |
| 715 |
out.Elem = p.walkType(u, nil, t.Elem()) |
| 716 |
out.Len = in.(*gotypes.Array).Len() |
| 717 |
return out |
| 718 |
case *gotypes.Chan: |
| 719 |
out := u.Type(name) |
| 720 |
out.GoType = in |
| 721 |
if out.Kind != types.Unknown { |
| 722 |
return out |
| 723 |
} |
| 724 |
out.Kind = types.Chan |
| 725 |
out.Elem = p.walkType(u, nil, t.Elem()) |
| 726 |
// TODO: need to store direction, otherwise raw type name |
| 727 |
// cannot be properly written. |
| 728 |
return out |
| 729 |
case *gotypes.Basic: |
| 730 |
out := u.Type(types.Name{ |
| 731 |
Package: "", // This is a magic package name in the Universe. |
| 732 |
Name: t.Name(), |
| 733 |
}) |
| 734 |
out.GoType = in |
| 735 |
if out.Kind != types.Unknown { |
| 736 |
return out |
| 737 |
} |
| 738 |
out.Kind = types.Unsupported |
| 739 |
return out |
| 740 |
case *gotypes.Signature: |
| 741 |
out := u.Type(name) |
| 742 |
out.GoType = in |
| 743 |
if out.Kind != types.Unknown { |
| 744 |
return out |
| 745 |
} |
| 746 |
out.Kind = types.Func |
| 747 |
out.Signature = p.convertSignature(u, t) |
| 748 |
return out |
| 749 |
case *gotypes.Interface: |
| 750 |
out := u.Type(name) |
| 751 |
out.GoType = in |
| 752 |
if out.Kind != types.Unknown { |
| 753 |
return out |
| 754 |
} |
| 755 |
out.Kind = types.Interface |
| 756 |
t.Complete() |
| 757 |
for i := 0; i < t.NumMethods(); i++ { |
| 758 |
if out.Methods == nil { |
| 759 |
out.Methods = map[string]*types.Type{} |
| 760 |
} |
| 761 |
method := t.Method(i) |
| 762 |
name := goNameToName(method.String()) |
| 763 |
mt := p.walkType(u, &name, method.Type()) |
| 764 |
mt.CommentLines = p.docComment(method.Pos()) |
| 765 |
out.Methods[method.Name()] = mt |
| 766 |
} |
| 767 |
return out |
| 768 |
case *gotypes.Named: |
| 769 |
var out *types.Type |
| 770 |
switch t.Underlying().(type) { |
| 771 |
case *gotypes.Named, *gotypes.Basic, *gotypes.Map, *gotypes.Slice: |
| 772 |
name := goNameToName(t.String()) |
| 773 |
out = u.Type(name) |
| 774 |
out.GoType = in |
| 775 |
if out.Kind != types.Unknown { |
| 776 |
return out |
| 777 |
} |
| 778 |
out.Kind = types.Alias |
| 779 |
out.Underlying = p.walkType(u, nil, t.Underlying()) |
| 780 |
case *gotypes.Struct, *gotypes.Interface: |
| 781 |
name := goNameToName(t.String()) |
| 782 |
tpMap := map[string]*types.Type{} |
| 783 |
if t.TypeParams().Len() != 0 { |
| 784 |
// Remove generics, then readd them without the encoded |
| 785 |
// type, e.g. Foo[T any] => Foo[T] |
| 786 |
var tpNames []string |
| 787 |
for i := 0; i < t.TypeParams().Len(); i++ { |
| 788 |
tp := t.TypeParams().At(i) |
| 789 |
tpName := tp.Obj().Name() |
| 790 |
tpNames = append(tpNames, tpName) |
| 791 |
tpMap[tpName] = p.walkType(u, nil, tp.Constraint()) |
| 792 |
} |
| 793 |
name.Name = fmt.Sprintf("%s[%s]", strings.SplitN(name.Name, "[", 2)[0], strings.Join(tpNames, ",")) |
| 794 |
} |
| 795 |
|
| 796 |
if out := u.Type(name); out.Kind != types.Unknown { |
| 797 |
out.GoType = in |
| 798 |
return out // short circuit if we've already made this. |
| 799 |
} |
| 800 |
out = p.walkType(u, &name, t.Underlying()) |
| 801 |
out.TypeParams = tpMap |
| 802 |
default: |
| 803 |
// gotypes package makes everything "named" with an |
| 804 |
// underlying anonymous type--we remove that annoying |
| 805 |
// "feature" for users. This flattens those types |
| 806 |
// together. |
| 807 |
name := goNameToName(t.String()) |
| 808 |
if out := u.Type(name); out.Kind != types.Unknown { |
| 809 |
return out // short circuit if we've already made this. |
| 810 |
} |
| 811 |
out = p.walkType(u, &name, t.Underlying()) |
| 812 |
} |
| 813 |
// If the underlying type didn't already add methods, add them. |
| 814 |
// (Interface types will have already added methods.) |
| 815 |
if len(out.Methods) == 0 { |
| 816 |
for i := 0; i < t.NumMethods(); i++ { |
| 817 |
if out.Methods == nil { |
| 818 |
out.Methods = map[string]*types.Type{} |
| 819 |
} |
| 820 |
method := t.Method(i) |
| 821 |
name := goNameToName(method.String()) |
| 822 |
mt := p.walkType(u, &name, method.Type()) |
| 823 |
mt.CommentLines = p.docComment(method.Pos()) |
| 824 |
out.Methods[method.Name()] = mt |
| 825 |
} |
| 826 |
} |
| 827 |
return out |
| 828 |
case *gotypes.TypeParam: |
| 829 |
// DO NOT retrieve the type from the universe. The default type-param name is only the |
| 830 |
// generic variable name. Ideally, it would be namespaced by package and struct but it is |
| 831 |
// not. Thus, if we try to use the universe, we would start polluting it. |
| 832 |
// e.g. if Foo[T] and Bar[T] exists, we'd mistakenly use the same type T for both. |
| 833 |
return &types.Type{ |
| 834 |
Name: name, |
| 835 |
Kind: types.TypeParam, |
| 836 |
} |
| 837 |
default: |
| 838 |
out := u.Type(name) |
| 839 |
out.GoType = in |
| 840 |
if out.Kind != types.Unknown { |
| 841 |
return out |
| 842 |
} |
| 843 |
out.Kind = types.Unsupported |
| 844 |
klog.Warningf("Making unsupported type entry %q for: %#v\n", out, t) |
| 845 |
return out |
| 846 |
} |
| 847 |
} |
| 848 |
|
| 849 |
func (p *Parser) addFunction(u types.Universe, useName *types.Name, in *gotypes.Func) *types.Type { |
| 850 |
name := goFuncNameToName(in.String()) |
| 851 |
if useName != nil { |
| 852 |
name = *useName |
| 853 |
} |
| 854 |
out := u.Function(name) |
| 855 |
out.Kind = types.DeclarationOf |
| 856 |
out.Underlying = p.walkType(u, nil, in.Type()) |
| 857 |
return out |
| 858 |
} |
| 859 |
|
| 860 |
func (p *Parser) addVariable(u types.Universe, useName *types.Name, in *gotypes.Var) *types.Type { |
| 861 |
name := goVarNameToName(in.String()) |
| 862 |
if useName != nil { |
| 863 |
name = *useName |
| 864 |
} |
| 865 |
out := u.Variable(name) |
| 866 |
out.Kind = types.DeclarationOf |
| 867 |
out.Underlying = p.walkType(u, nil, in.Type()) |
| 868 |
return out |
| 869 |
} |
| 870 |
|
| 871 |
func (p *Parser) addConstant(u types.Universe, useName *types.Name, in *gotypes.Const) *types.Type { |
| 872 |
name := goVarNameToName(in.String()) |
| 873 |
if useName != nil { |
| 874 |
name = *useName |
| 875 |
} |
| 876 |
out := u.Constant(name) |
| 877 |
out.Kind = types.DeclarationOf |
| 878 |
out.Underlying = p.walkType(u, nil, in.Type()) |
| 879 |
|
| 880 |
var constval string |
| 881 |
|
| 882 |
// For strings, we use `StringVal()` to get the un-truncated, |
| 883 |
// un-quoted string. For other values, `.String()` is preferable to |
| 884 |
// get something relatively human readable (especially since for |
| 885 |
// floating point types, `ExactString()` will generate numeric |
| 886 |
// expressions using `big.(*Float).Text()`. |
| 887 |
switch in.Val().Kind() { |
| 888 |
case constant.String: |
| 889 |
constval = constant.StringVal(in.Val()) |
| 890 |
default: |
| 891 |
constval = in.Val().String() |
| 892 |
} |
| 893 |
|
| 894 |
out.ConstValue = &constval |
| 895 |
return out |
| 896 |
} |