reports

type Asset struct {
	// Path is the asset path, as mounted.
	Path string

	// Templates holds the templates the asset declares, the one named after the asset first,
	// then those declared by a "define" statement, ordered by name.
	Templates []Template
}

type Audit struct {
	// Overridden lists the templates that more than one asset declared, with the definition that
	// stands and the ones it replaced.
	Overridden []Override

	// Unused lists the templates nothing else calls, ordered by name.
	//
	// A repository scoped with [WithRoots] leaves its roots out of this, since a run starts there.
	// One that keeps every template it read cannot tell an entry point from a dead template, so
	// its entry points are listed too.
	Unused []string

	// Empty lists the templates that render nothing, ordered by name. An asset holding only
	// "define" statements declares one, under its own name.
	Empty []string

	// Dynamic lists the templates invoking a function held by their data, with the "call" builtin.
	//
	// Nothing settles such a call before the template runs, so what it reaches is unknown to the
	// repository and to the documentation alike.
	Dynamic []string

	// UnusedFuncs lists the func map entries no template calls, ordered by name.
	UnusedFuncs []string
}

type Dependency struct {
	// Name is the template called.
	Name string

	// Data is the path handed to it, rooted like the paths of the calling template.
	//
	// It is "." when the caller hands over its own data, and empty when the analysis could not
	// place it.
	Data string

	// Folded is the number of paths the called template reads, itself and through its own calls.
	//
	// It locates the weight of a caller's own fold, so a reader can see which of its calls to
	// follow first.
	Folded int
}

type Documentation struct {
	// Assets holds one entry per asset that declares a template, ordered by path.
	Assets []Asset
}

type DumpOption func(dumpOptions) dumpOptions

type Override struct {
	// Name is the template that was declared more than once.
	Name string

	// Standing is the path of the asset whose definition the repository holds.
	Standing string

	// Replaced holds the paths of the assets whose definitions it replaced, in the order they
	// were read.
	Replaced []string
}

type Root struct {
	// Field is the field the paths start at.
	Field string

	// Paths is how many of them there are.
	Paths int
}

type Template struct {
	// Name is what [github.com/go-openapi/codegen/templates-repo.Repository.Get] answers to.
	Name string

	// Doc holds the comments documenting the template, one entry per comment.
	Doc []string

	// Reads lists the data paths the template may read, rooted at the data it is executed on.
	//
	// It closes over every branch, so it describes what the data must be able to answer, not a
	// list of what it must hold: a path guarded by a condition may never be reached.
	Reads []string

	// RootReads lists the paths read through "$", a reach past the current dot back to the data
	// the template was executed on.
	RootReads []string

	// Funcs lists the func map functions the template calls, sorted. Builtins are left out.
	Funcs []string

	// Dependencies lists the templates this one calls, with the data handed to each.
	Dependencies []Dependency

	// UsedBy lists the templates that refer to this one directly, sorted.
	UsedBy []string

	// Inner reports whether the template is declared by a "define" statement rather than by an
	// asset of its own.
	Inner bool

	// Empty reports whether the template holds nothing but white space and comments, so that
	// executing it renders nothing.
	//
	// An asset made of "define" statements alone declares such a template under its own name,
	// which is reachable like any other and renders nothing.
	Empty bool

	// Unresolved counts the data accesses the analysis could not place, because the value they
	// hang from comes out of a function call.
	Unresolved int

	// Dynamic reports whether the template invokes a function held by its data, with the builtin
	// "call", which makes its contract incomplete by construction.
	Dynamic bool

	// Transitive holds the data the template reads once the templates it calls are folded into it.
	Transitive Transitive
}

type Transitive struct {
	// Reads lists the data paths the template may read, itself or through the templates it calls.
	Reads []string

	// Funcs lists the func map functions reached the same way.
	Funcs []string

	// Reaches lists the templates it calls, directly or not, sorted.
	Reaches []string

	// Unresolved counts what could not be folded in.
	Unresolved int

	// Recursive reports whether the closure ran into a template that calls itself, directly or
	// not, and stopped there.
	Recursive bool
}

type Weights struct {
	// Heavy holds the fields more than one path hangs from, heaviest first.
	Heavy []Root

	// Single holds the fields read once, sorted.
	Single []string
}