project

Documentation

Overview

Package project finds the source and test files the tools analyze.

Index

• Variables
• func AtRoot(rel string) string
• func Changed() ([]string, error)
• func ChangedSince[T any](ctx context.Context, ref string, ...) (changed map[string]T, renamed map[string]string, err error)
• func ChangedSinceAt[T any](ctx context.Context, dir, ref string, ...) (changed map[string]T, renamed map[string]string, err error)
• func DeletedSince(ref string) ([]string, error)
• func DeletedSinceAt(ctx context.Context, dir, ref string) ([]string, error)
• func FindUp(ctx context.Context, path string, markers ...string) string
• func FlutterPlatformDir(dir string) bool
• func FromRoot(path string) string
• func FromRootOf(root, path string) string
• func GeneratedDart(path string) bool
• func Head() (string, error)
• func HeadAt(ctx context.Context, dir string) (string, error)
• func IsBuildOutput(ctx context.Context, dir string) bool
• func IsBuildOutputWithIgnore(ctx context.Context, dir string, ...) bool
• func NoBytecodeEnv(env []string) []string
• func NodeBin(dir, name string) string
• func NodeModule(dir, name string) string
• func PackageManager(dir string) string
• func ParseFile(ctx context.Context, path string) (*lang.File, error)
• func ReadCommittedAt(ctx context.Context, dir, ref, path string) ([]byte, error)
• func Rel(path string) string
• func RenamesSince(ref string) (map[string]string, error)
• func RenamesSinceAt(ctx context.Context, dir, ref string) (map[string]string, error)
• func RenamesUncommitted() (map[string]string, error)
• func RenamesUncommittedAt(ctx context.Context, dir string) (map[string]string, error)
• func ResolveAt(ctx context.Context, dir, ref string) (string, error)
• func Root() string
• func RootOf(dir string) string
• func TrackedAt(ctx context.Context, dir string) ([]string, error)
• func WalkDir(ctx context.Context, root string, fn WalkFunc) error
• type Files
  • func Discover(ctx context.Context, roots []string) (Files, error)
  • func DiscoverWithBuildOutput(ctx context.Context, roots []string, ...) (Files, error)
• type LineRange
• type NoGitError
  • func (e *NoGitError) Error() string
• type Surroundings
  • func (Surroundings) Abs(_ context.Context, path string) (string, bool)
  • func (Surroundings) Exists(_ context.Context, path string) bool
  • func (Surroundings) Read(ctx context.Context, path string) ([]byte, bool)
  • func (Surroundings) WorkingDir(context.Context) (string, bool)
• type WalkFunc

Variables

var ErrBadRef = errors.New("not a commit in this repository")

ErrBadRef is returned by ChangedSince for a ref git cannot resolve to a commit.

Functions

func AtRoot

func AtRoot(rel string) string

AtRoot is the absolute path of rel, a path a snapshot records.

func Changed

func Changed() ([]string, error)

Changed returns the supported files under the working directory that git reports as added or modified, staged or not, plus untracked files, as paths relative to the working directory. Git lists them NUL-terminated, so a name with spaces or non-ASCII letters arrives unquoted.

func ChangedSince

func ChangedSince[T any](ctx context.Context, ref string, judge func(file, base *lang.File, lines []LineRange) T) (changed map[string]T, renamed map[string]string, err error)

ChangedSince returns what judge makes of each file the commits since ref changed: git diff ref...HEAD, so a branch's own commits whatever the base did since, and never the working tree. Each supported file under the working directory that the range changed or renamed is a key, by absolute path, even when none of its lines changed; its value is judge's, given the file as HEAD holds it, so an uncommitted edit neither adds a line nor moves one, the file as the range's start, the merge base, held it, under the name it had there, nil when it had none or one of another language, and the lines the range changed in HEAD's version. A deleted line counts as a change of the lines either side of it, marked Deletion, and a move is no change, so a file renamed unchanged has no lines. Both files are open only while judge runs. renamed maps each file the range renamed, by its absolute path, to the absolute path it had at ref. It reads under ctx: once ctx is done it starts no command and returns its cause.

func ChangedSinceAt

func ChangedSinceAt[T any](ctx context.Context, dir, ref string, judge func(file, base *lang.File, lines []LineRange) T) (changed map[string]T, renamed map[string]string, err error)

ChangedSinceAt is the same query under an explicit caller directory.

func DeletedSince

func DeletedSince(ref string) ([]string, error)

DeletedSince returns each supported file the commits since ref deleted, by the absolute path it had, of those under the working directory, as ChangedSince finds the files it changed: git diff ref...HEAD, committed changes only. A file renamed is not deleted: ChangedSince maps it to the path it had. ref must be one ChangedSince accepted.

func DeletedSinceAt

func DeletedSinceAt(ctx context.Context, dir, ref string) ([]string, error)

DeletedSinceAt reads the committed deletion inventory under caller ctx/dir.

func FindUp

func FindUp(ctx context.Context, path string, markers ...string) string

FindUp returns the nearest directory at or above path's directory that contains one of markers on disk, or "" when none does, by lang's walk up through Surroundings.

func FlutterPlatformDir

func FlutterPlatformDir(dir string) bool

FlutterPlatformDir reports whether dir is a platform folder of a Flutter app, as discovery leaves it out: one of the folders flutter create writes beside a pubspec.yaml that depends on the flutter SDK. A Dart package's strict coverage evidence leaves them out the same way.

func FromRoot

func FromRoot(path string) string

FromRoot is path, absolute or relative to the working directory, as a snapshot records it: relative to the project root and slash-separated. A path outside the root stays absolute.

func FromRootOf

func FromRootOf(root, path string) string

FromRootOf is FromRoot for the project whose root is root, which need not be the working directory's: path made absolute, named as the snapshot domain names it (snapshot.Key).

func GeneratedDart

func GeneratedDart(path string) bool

GeneratedDart reports whether path is generated Dart, as discovery leaves it out: a build_runner or protoc suffix, flutter's plugin registrant, what gen-l10n wrote as an l10n.yaml in a folder above it says, or a file whose leading comments carry source_gen's marker.

func Head

func Head() (string, error)

Head returns the id of the HEAD commit of the working directory's repository, or a *NoGitError when it is in none or the repository has no commit yet.

func HeadAt

func HeadAt(ctx context.Context, dir string) (string, error)

HeadAt observes HEAD in dir without changing process cwd.

func IsBuildOutput

func IsBuildOutput(ctx context.Context, dir string) bool

IsBuildOutput reports whether dir is build or test output rather than source: it has a build output name, and it sits beside a manifest of a tool that writes there, or git ignores it, asked under ctx.

func IsBuildOutputWithIgnore

func IsBuildOutputWithIgnore(ctx context.Context, dir string, ignored func(ctx context.Context, dir string) bool) bool

IsBuildOutputWithIgnore reports whether dir is a known build directory with a nearby build manifest or whether ignored, asked under ctx, says it is ignored. The callback lets committed-input callers evaluate ignore rules against a frozen tree instead of the live checkout.

func NoBytecodeEnv

func NoBytecodeEnv(env []string) []string

NoBytecodeEnv is env, or the parent's environment when env is nil, with Python told to write no bytecode. Python takes the bytecode in __pycache__ as fresh while its source keeps the mtime, in whole seconds, and the size it was compiled from, so a mutant of the same size written within the second a run compiled its source would run the unmutated code. Every test and coverage command itos-cc runs gets it: one that writes no bytecode can leave none stale, and leaves no __pycache__ in the project's own tree. A command that is not Python ignores it, and a shell line may start Python without itos-cc knowing.

func NodeBin

func NodeBin(dir, name string) string

NodeBin is the installed executable name as dir resolves it, or "" when no package at or above dir installed one. Tools run from here rather than through npx, which downloads and runs whatever version the registry has when the project did not install one.

func NodeModule

func NodeModule(dir, name string) string

NodeModule is the installed package name as dir resolves it, in the nearest node_modules at or above dir, or "" when it is not installed.

func PackageManager

func PackageManager(dir string) string

PackageManager is the package manager a Node project at dir declares: the packageManager field of the nearest package.json that has one, or the nearest lockfile, so a workspace member uses its root's. It is npm when nothing says otherwise.

func ParseFile

func ParseFile(ctx context.Context, path string) (*lang.File, error)

ParseFile reads and parses path, lang naming it through Surroundings, the disk. A language lang does not know is refused before anything is read.

func ReadCommittedAt

func ReadCommittedAt(ctx context.Context, dir, ref, path string) ([]byte, error)

ReadCommittedAt reads an immutable root-relative blob. It exports nothing and follows no filesystem target; frozen materialization/mode admission is separate.

func Rel

func Rel(path string) string

Rel returns path relative to the working directory when it is inside it, and path unchanged otherwise. Reports use it so output reads like the command line that produced it.

func RenamesSince

func RenamesSince(ref string) (map[string]string, error)

RenamesSince maps each file the commits since ref renamed, by the absolute path it had at ref, to the absolute path it has at HEAD, across the whole repository of the working directory, both under the project root (Root): git diff -M ref...HEAD, the rename detection ChangedSince follows renames by. ref must be one ChangedSince accepted.

func RenamesSinceAt

func RenamesSinceAt(ctx context.Context, dir, ref string) (map[string]string, error)

RenamesSinceAt and RenamesUncommittedAt use the same repository-wide map under a caller directory/context, independently of --since file narrowing.

func RenamesUncommitted

func RenamesUncommitted() (map[string]string, error)

RenamesUncommitted maps each file the working tree has renamed against HEAD, as RenamesSince maps a range's: git diff -M HEAD, which sees a rename once the new file is tracked, staged as git mv leaves it or added with git add. A plain mv with nothing staged is a deletion and an untracked file to git, so no rename. It returns a *NoGitError outside a git repository, or in one with no commit yet.

func RenamesUncommittedAt

func RenamesUncommittedAt(ctx context.Context, dir string) (map[string]string, error)

func ResolveAt

func ResolveAt(ctx context.Context, dir, ref string) (string, error)

ResolveAt validates a commit spelling, preserving invalid-ref classification.

func Root

func Root() string

Root is the project root of the working directory: where .metrics/ and itos-cc.yaml live, and what every path a snapshot records is relative to. It is the git top level of the working directory, or the working directory itself outside a git repository. It is absolute, in the form os.Getwd gives.

func RootOf

func RootOf(dir string) string

RootOf is the project root of the directory dir, absolute: the git top level of dir, or dir itself outside a git repository. It is found from dir as given, so a root reached through a symbolic link keeps its form.

func TrackedAt

func TrackedAt(ctx context.Context, dir string) ([]string, error)

TrackedAt lists the files git tracks beneath dir, the paths its index holds, slash-separated and relative to dir. Git lists them NUL-terminated, so a name with spaces or non-ASCII letters arrives unquoted. A tracked file deleted from the working tree is still listed. Outside a work tree, or with no git to ask, it returns a *NoGitError.

func WalkDir

func WalkDir(ctx context.Context, root string, fn WalkFunc) error

WalkDir walks the tree at root as filepath.WalkDir does, root first, then each directory's entries in lexical order, calling fn under ctx; fn may return filepath.SkipDir or filepath.SkipAll as it may there. It hands fn the context, so a callback that does I/O takes it first rather than capturing it. Once ctx is done it visits nothing more and returns its cause.

Types

type Files

type Files = selection.Files

Files are the supported source files under some roots, split into production code and test code. Paths are absolute and sorted.

func Discover

func Discover(ctx context.Context, roots []string) (Files, error)

Discover walks roots (files or directories) under ctx and classifies every file in a supported language. It never walks into a skipped, hidden or build output directory, or a Flutter app's platform folder, and takes no generated Dart. A root that names a file is taken even if it would be skipped while walking. Once ctx is done it returns its cause.

func DiscoverWithBuildOutput

func DiscoverWithBuildOutput(ctx context.Context, roots []string, isBuildOutput func(ctx context.Context, dir string) bool) (Files, error)

DiscoverWithBuildOutput is Discover with an explicit build-output classifier, asked under ctx. All other source/test, hidden-directory, fixture, dependency, Flutter and generated-Dart rules remain the same.

type LineRange

type LineRange struct {
	Start, End int
	Deletion   bool
}

LineRange is a range of the lines of HEAD's version of a file that the commits since a ref changed, both ends included; Deletion marks the two lines either side of a hunk that only deleted lines.

type NoGitError

type NoGitError struct{ Reason string }

NoGitError is ChangedSince's error when the working directory is not in a git repository, or git cannot run. Reason is git's own message.

func (*NoGitError) Error

func (e *NoGitError) Error() string

type Surroundings

type Surroundings struct{}

Surroundings are lang's Surroundings as this process sees the disk: the calls lang made itself before it asked a port (os.Stat, os.ReadFile, os.Getwd and filepath.Abs), each answer false where the call failed.

func (Surroundings) Abs

func (Surroundings) Abs(_ context.Context, path string) (string, bool)

Abs is filepath.Abs's answer, false when it fails.

func (Surroundings) Exists

func (Surroundings) Exists(_ context.Context, path string) bool

Exists says whether path can be stat'ed: a path that cannot, for any reason, is not there. A stat ends at once, so ctx has nothing to cut short.

func (Surroundings) Read

func (Surroundings) Read(ctx context.Context, path string) ([]byte, bool)

Read is what the file at path holds, false when it cannot be read. A done ctx reads nothing; a read under way runs to its end.

func (Surroundings) WorkingDir

func (Surroundings) WorkingDir(context.Context) (string, bool)

WorkingDir is os.Getwd's answer, false when it fails.

type WalkFunc

type WalkFunc func(ctx context.Context, path string, d fs.DirEntry, err error) error

WalkFunc is what WalkDir calls for each file and directory, as filepath.WalkDir calls its fs.WalkDirFunc, under the walk's context.