modgraph

type DynamicPolicy string

type FileSet struct {
	// Module are the source files the distribution installs.
	Module []string
	// Reachable are the ones the closure imports.
	Reachable []string
}

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

type Language interface {
	// ID names the language, for evidence lines.
	ID() string

	// Roots turns the image config into entry modules, or explains through
	// taints why it could not. extra is the user's --roots values.
	//
	// A Language that cannot find an entrypoint is expected to escalate --
	// root every installed module -- and say so with a taint, never to return
	// an empty root set. No roots means nothing is reachable, which reads as
	// an image where no code runs.
	Roots(extra []string) ([]Root, []Taint, error)

	// Imports lists the specifiers one file references, plus any taint the
	// file itself raises (a computed import, a body that would not parse).
	Imports(file string) ([]Spec, []Taint, error)

	// Resolve maps a specifier referenced from a file onto the files it loads.
	// A specifier can resolve to more than one path -- a PEP 420 namespace
	// package merges across sys.path entries -- and ok is false when it
	// resolved to nothing, which the caller records as an unresolved-import
	// taint scoped to that specifier.
	Resolve(from string, spec Spec) ([]string, bool)

	// IsModule reports whether a path is code this language would load. It is
	// what makes a file eligible to be counted at all, and it must not read
	// the file: it is called once per file in an inventory.
	IsModule(path string) bool
}

type Node struct {
	// Path is the canonical tree-absolute path.
	Path string

	// Root, Why and Kind describe how the walk started here, if it did.
	Root bool
	Why  string
	Kind RootKind

	// Reachable says the walk arrived here. Every node in the graph is
	// reachable -- unlike elfgraph, which indexes unreachable objects too --
	// but the field is kept so evaluate.go reads the same in both.
	Reachable bool

	// Imports records what this file resolved to, keyed by specifier. A
	// specifier that resolved to nothing maps to nil and is also a taint.
	Imports map[string][]string

	// ImportedBy is every file that imported this one, in discovery order.
	// Empty for a root nothing else reaches.
	ImportedBy []string
}

type Options struct {
	// Roots are extra entry files or module names from --roots, passed to the
	// Language because resolving them is language-specific.
	Roots []string

	// Dynamic decides whether a computed import blocks a conclusion.
	Dynamic DynamicPolicy

	// Logf, if set, receives progress lines.
	Logf func(format string, args ...any)
}

type Root struct {
	Path string
	Why  string
	Kind RootKind
}

type RootKind string

type Spec struct {
	// Name is the specifier verbatim: "yaml", ".loader", "@scope/pkg/sub".
	Name string

	// Line is where it appears, for evidence. Zero when unknown.
	Line int

	// Dynamic marks a specifier that came from importlib.import_module or
	// require() with a literal argument. It resolves like any other import --
	// the argument is right there -- and is only flagged so evidence can say
	// how the edge was found.
	Dynamic bool

	// Optional marks a specifier that may legitimately resolve to nothing, and
	// so raises no taint when it does. "from pkg import Thing" produces one:
	// Thing might be a submodule, and might equally be a class defined in
	// pkg/__init__.py. Without this every such line would report a missing
	// module, and a taint that fires on correct code teaches a reader to
	// ignore taints.
	Optional bool
}

type Taint struct {
	Kind TaintKind `json:"kind"`

	// Detail is the human-readable statement of what was observed.
	Detail string `json:"detail"`

	// Path is the file that caused it, when there is one.
	Path string `json:"path,omitempty"`

	// Spec scopes a taint to the specifier that went unresolved. Conclusions
	// about every other module are unaffected by it.
	Spec string `json:"spec,omitempty"`

	// Scope narrows a taint to the distributions it can affect, by import
	// name. A dynamic import inside one distribution says nothing about the
	// rest of the image, and scoping it is what keeps the whole scan from
	// being tainted by one plugin loader.
	Scope []string `json:"scope,omitempty"`

	// Blocking says whether this taint stops a not_affected conclusion.
	// Blocking is a field rather than a property of Kind because
	// --dynamic-import-policy=assume-none demotes a dynamic import to a note:
	// the user asserted the risk away, and the record should still show it.
	Blocking bool `json:"blocking"`

	// Global says the taint applies to every distribution rather than to the
	// scope named by Spec or Scope.
	Global bool `json:"global,omitempty"`
}

type TaintKind string