pkgtree

Documentation

Index

• func CopyPackages(p map[string]PackageOrErr, ...) map[string]PackageOrErr
• type ConflictingImportComments
  • func (e *ConflictingImportComments) Error() string
• type IgnoredRuleset
  • func NewIgnoredRuleset(ig []string) *IgnoredRuleset
  • func (ir *IgnoredRuleset) IsIgnored(path string) bool
  • func (ir *IgnoredRuleset) Len() int
  • func (ir *IgnoredRuleset) ToSlice() []string
• type LocalImportsError
  • func (e *LocalImportsError) Error() string
• type NonCanonicalImportRoot
  • func (e *NonCanonicalImportRoot) Error() string
• type Package
• type PackageOrErr
• type PackageTree
  • func ListPackages(fileRoot, importRoot string) (PackageTree, error)
  • func (t PackageTree) Copy() PackageTree
  • func (t PackageTree) ToReachMap(main, tests, backprop bool, ignore *IgnoredRuleset) (ReachMap, map[string]*ProblemImportError)
  • func (t PackageTree) TrimHiddenPackages(main, tests bool, ignore *IgnoredRuleset) PackageTree
• type ProblemImportError
  • func (e *ProblemImportError) Error() string
• type ReachMap
  • func (rm ReachMap) FlattenFn(exclude func(string) bool) []string

Functions

func CopyPackages

func CopyPackages(p map[string]PackageOrErr, fn func(string, PackageOrErr) (string, PackageOrErr)) map[string]PackageOrErr

CopyPackages returns a deep copy of p, optionally modifying the entries with fn.

Types

type ConflictingImportComments

type ConflictingImportComments struct {
	ImportPath                string   // An import path referring to this package
	ConflictingImportComments []string // All distinct "canonical" paths encountered in the package files
}

ConflictingImportComments indicates that the package declares more than one different canonical path.

func (*ConflictingImportComments) Error

func (e *ConflictingImportComments) Error() string

type IgnoredRuleset

type IgnoredRuleset struct {
	// contains filtered or unexported fields
}

IgnoredRuleset comprises a set of rules for ignoring import paths. It can manage both literal and prefix-wildcard matches.

func NewIgnoredRuleset

func NewIgnoredRuleset(ig []string) *IgnoredRuleset

NewIgnoredRuleset processes a set of strings into an IgnoredRuleset. Strings that end in "*" are treated as wildcards, where any import path with a matching prefix will be ignored. IgnoredRulesets are immutable once created.

Duplicate and redundant (i.e. a literal path that has a prefix of a wildcard path) declarations are discarded. Consequently, it is possible that the returned IgnoredRuleset may have a smaller Len() than the input slice.

func (*IgnoredRuleset) IsIgnored

func (ir *IgnoredRuleset) IsIgnored(path string) bool

IsIgnored indicates whether the provided path should be ignored, according to the ruleset.

func (*IgnoredRuleset) Len

func (ir *IgnoredRuleset) Len() int

Len indicates the number of rules in the ruleset.

func (*IgnoredRuleset) ToSlice

func (ir *IgnoredRuleset) ToSlice() []string

ToSlice converts the contents of the IgnoredRuleset to a string slice.

This operation is symmetrically dual to NewIgnoredRuleset.

type LocalImportsError

type LocalImportsError struct {
	ImportPath   string
	Dir          string
	LocalImports []string
}

TODO(sdboyer) add a Files property once we're doing our own per-file parsing

func (*LocalImportsError) Error

func (e *LocalImportsError) Error() string

type NonCanonicalImportRoot

type NonCanonicalImportRoot struct {
	ImportRoot string // A root path that is being used to import a package
	Canonical  string // A canonical path declared by the package being imported
}

NonCanonicalImportRoot reports the situation when the dependee imports a package via something other than the package's declared canonical path.

func (*NonCanonicalImportRoot) Error

func (e *NonCanonicalImportRoot) Error() string

type Package

type Package struct {
	Name        string   // Package name, as declared in the package statement
	ImportPath  string   // Full import path, including the prefix provided to ListPackages()
	CommentPath string   // Import path given in the comment on the package statement
	Imports     []string // Imports from all go and cgo files
	TestImports []string // Imports from all go test files (in go/build parlance: both TestImports and XTestImports)
}

Package represents a Go package. It contains a subset of the information go/build.Package does.

type PackageOrErr

type PackageOrErr struct {
	P   Package
	Err error
}

PackageOrErr stores the results of attempting to parse a single directory for Go source code.

type PackageTree

type PackageTree struct {
	ImportRoot string
	Packages   map[string]PackageOrErr
}

A PackageTree represents the results of recursively parsing a tree of packages, starting at the ImportRoot. The results of parsing the files in the directory identified by each import path - a Package or an error - are stored in the Packages map, keyed by that import path.

func ListPackages

func ListPackages(fileRoot, importRoot string) (PackageTree, error)

ListPackages reports Go package information about all directories in the tree at or below the provided fileRoot.

The importRoot parameter is prepended to the relative path when determining the import path for each package. The obvious case is for something typical, like:

fileRoot = "/home/user/go/src/github.com/foo/bar"
importRoot = "github.com/foo/bar"

where the fileRoot and importRoot align. However, if you provide:

fileRoot = "/home/user/workspace/path/to/repo"
importRoot = "github.com/foo/bar"

then the root package at path/to/repo will be ascribed import path "github.com/foo/bar", and the package at "/home/user/workspace/path/to/repo/baz" will be "github.com/foo/bar/baz".

A PackageTree is returned, which contains the ImportRoot and map of import path to PackageOrErr - each path under the root that exists will have either a Package, or an error describing why the directory is not a valid package.

func (PackageTree) Copy

func (t PackageTree) Copy() PackageTree

Copy copies the PackageTree.

This is really only useful as a defensive measure to prevent external state mutations.

func (PackageTree) ToReachMap

func (t PackageTree) ToReachMap(main, tests, backprop bool, ignore *IgnoredRuleset) (ReachMap, map[string]*ProblemImportError)

 map[string][]string{
	"A": []string{},
	"A/bar": []string{"B/baz"},
 }

func (PackageTree) TrimHiddenPackages

func (t PackageTree) TrimHiddenPackages(main, tests bool, ignore *IgnoredRuleset) PackageTree

reachability checks. Setting 'main' to true will additionally result in main packages being trimmed.

"ignored" designates import paths, or patterns of import paths, where the corresponding packages should be excluded from reachability checks, if encountered. Ignored packages are also removed from the final set.

Note that it is not recommended to call this method if the goal is to obtain a set of tree-external imports; calling ToReachMap and FlattenFn will achieve the same effect.

type ProblemImportError

type ProblemImportError struct {
	// The import path of the package with some problem rendering it
	// unimportable.
	ImportPath string
	// The path to the internal package the problem package imports that is the
	// original cause of this issue. If empty, the package itself is the
	// problem.
	Cause []string
	// The actual error from ListPackages that is undermining importability for
	// this package.
	Err error
}

ProblemImportError describes the reason that a particular import path is not safely importable.

func (*ProblemImportError) Error

func (e *ProblemImportError) Error() string

Error formats the ProblemImportError as a string, reflecting whether the error represents a direct or transitive problem.

type ReachMap

type ReachMap map[string]struct {
	Internal, External []string
}

ReachMap maps a set of import paths (keys) to the sets of transitively reachable tree-internal packages, and all the tree-external packages reachable through those internal packages.

See PackageTree.ToReachMap() for more information.

func (ReachMap) FlattenFn

func (rm ReachMap) FlattenFn(exclude func(string) bool) []string

FlattenFn flattens a reachmap into a sorted, deduplicated list of all the external imports named by its contained packages, but excludes imports coming from packages with disallowed patterns in their names: any path element with a leading dot, a leading underscore, with the name "testdata".

Imports for which exclude returns true will be left out.