engine

package
v0.0.0-...-1952693 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 1, 2024 License: Apache-2.0 Imports: 47 Imported by: 0

Documentation

Overview

Package engine is the shac starlark main engine.

Index

Constants

View Source 
const DefaultEntryPoint = "shac.star"

DefaultEntryPoint is the default basename of Starlark files to search for and run.

Variables

View Source 
var ErrCheckFailed = errors.New("a check failed")

ErrCheckFailed is returned by Run() when at least one check failed.

The information will have been provided via the Report interface.

View Source 
var File_shac_proto protoreflect.FileDescriptor
View Source 
var (
	// Version is the current tool version.
	//
	// TODO(maruel): Add proper version, preferably from git tag.
	Version = shacVersion{0, 1, 18}
)

Functions

func Doc 

func Doc(src string) (string, error)

Doc returns the documentation for a source file.

src must be either a path to a source file or the string "stdlib".

func FSToDigest 

func FSToDigest(f fs.FS, prefix string) (string, error)

FSToDigest hash the content of a directory tree and return the hash.

Use a similar hashing mechanism than Go Modules. See implementation at https://github.com/golang/mod/blob/v0.10.0/sumdb/dirhash/hash.go or a more recent version.

The directories at root starting with a dot "." are ignored. This includes .git, .github, .vscode, etc. As such the digest may differ a bit from Go. This may be revisited.

func Fix 

func Fix(ctx context.Context, o *Options, quiet bool) error

Fix loads a main shac.star file from a root directory and runs checks defined in it, then applies suggested fixes to files on disk.

func Run 

func Run(ctx context.Context, o *Options) error

Run loads a main shac.star file from a root directory and runs it.

Types

type BacktraceableError 

type BacktraceableError interface {
	error
	// Backtrace returns a user-friendly error message describing the stack
	// of calls that led to this error, along with the error message itself.
	Backtrace() string
}

BacktraceableError is an error that has a starlark backtrace attached to it.

type CheckFilter 

type CheckFilter struct {
	FormatterFiltering FormatterFiltering
	// AllowList specifies checks to run. If non-empty, all other checks will be
	// skipped.
	AllowList []string
}

CheckFilter controls which checks are run.

type Cursor 

type Cursor struct {
	Line int
	Col  int
	// contains filtered or unexported fields
}

Cursor represents a point in a content; generally a source file but it can also be a change description.

type Dependency 

type Dependency struct {

	// url is the URL to the resource without the schema, e.g.
	// "github.com/shac/generic-checks".
	Url string `protobuf:"bytes,1,opt,name=url,proto3" json:"url,omitempty"`
	// alias is an optional shorthand alias. This is how this is referenced to in
	// load() statements.
	Alias string `protobuf:"bytes,2,opt,name=alias,proto3" json:"alias,omitempty"`
	// version is the pinned version to use the dependency.
	Version string `protobuf:"bytes,3,opt,name=version,proto3" json:"version,omitempty"`
	// contains filtered or unexported fields
}

Dependency is a starlark package containing a api.star file that will be loaded and become available through a load("@...") statement.

func (*Dependency) Descriptor deprecated 

func (*Dependency) Descriptor() ([]byte, []int)

Deprecated: Use Dependency.ProtoReflect.Descriptor instead.

func (*Dependency) GetAlias 

func (x *Dependency) GetAlias() string

func (*Dependency) GetUrl 

func (x *Dependency) GetUrl() string

func (*Dependency) GetVersion 

func (x *Dependency) GetVersion() string

func (*Dependency) ProtoMessage 

func (*Dependency) ProtoMessage()

func (*Dependency) ProtoReflect 

func (x *Dependency) ProtoReflect() protoreflect.Message

func (*Dependency) Reset 

func (x *Dependency) Reset()

func (*Dependency) String 

func (x *Dependency) String() string

func (*Dependency) Validate 

func (d *Dependency) Validate() error

Validate verifies a shac.textproto require block is valid.

It allows fetching from a Gerrit pending CL or a GitHub pending PR.

For Gerrit, it is guaranteed to be reproducible. For GitHub, ¯\_(ツ)_/¯.

type Document 

type Document struct {

	// Minimum shac version that is required to run this check. This enables
	// printing a better error message. It is a semver string.
	MinShacVersion string `protobuf:"bytes,1,opt,name=min_shac_version,json=minShacVersion,proto3" json:"min_shac_version,omitempty"`
	// When set to true, it is allowed to have checks that access the network.
	AllowNetwork bool `protobuf:"varint,2,opt,name=allow_network,json=allowNetwork,proto3" json:"allow_network,omitempty"`
	// Full list of all loaded package dependencies.
	Requirements *Requirements `protobuf:"bytes,3,opt,name=requirements,proto3" json:"requirements,omitempty"`
	// Digests of all direct and indirect dependencies to confirm the code was not
	// modified.
	Sum *Sum `protobuf:"bytes,4,opt,name=sum,proto3" json:"sum,omitempty"`
	// When set, refers to a local copy to use.
	VendorPath string `protobuf:"bytes,5,opt,name=vendor_path,json=vendorPath,proto3" json:"vendor_path,omitempty"`
	// File paths to ignore/un-ignore. Syntax matches that of .gitignore. See
	// https://git-scm.com/docs/gitignore.
	Ignore []string `protobuf:"bytes,6,rep,name=ignore,proto3" json:"ignore,omitempty"`
	// Whether to allow checks write access to the SCM root directory.
	// TODO(olivernewman): Remove this option once named caches and pass-throughs
	// are implemented.
	WritableRoot bool   `protobuf:"varint,7,opt,name=writable_root,json=writableRoot,proto3" json:"writable_root,omitempty"`
	Vars         []*Var `protobuf:"bytes,8,rep,name=vars,proto3" json:"vars,omitempty"`
	// Environment variables to pass through the sandbox.
	PassthroughEnv []*PassthroughEnv `protobuf:"bytes,9,rep,name=passthrough_env,json=passthroughEnv,proto3" json:"passthrough_env,omitempty"`
	// contains filtered or unexported fields
}

Document is the root message being decoded in a shac.textproto.

func (*Document) CheckVersion 

func (doc *Document) CheckVersion() error

func (*Document) Descriptor deprecated 

func (*Document) Descriptor() ([]byte, []int)

Deprecated: Use Document.ProtoReflect.Descriptor instead.

func (*Document) GetAllowNetwork 

func (x *Document) GetAllowNetwork() bool

func (*Document) GetIgnore 

func (x *Document) GetIgnore() []string

func (*Document) GetMinShacVersion 

func (x *Document) GetMinShacVersion() string

func (*Document) GetPassthroughEnv 

func (x *Document) GetPassthroughEnv() []*PassthroughEnv

func (*Document) GetRequirements 

func (x *Document) GetRequirements() *Requirements

func (*Document) GetSum 

func (x *Document) GetSum() *Sum

func (*Document) GetVars 

func (x *Document) GetVars() []*Var

func (*Document) GetVendorPath 

func (x *Document) GetVendorPath() string

func (*Document) GetWritableRoot 

func (x *Document) GetWritableRoot() bool

func (*Document) ProtoMessage 

func (*Document) ProtoMessage()

func (*Document) ProtoReflect 

func (x *Document) ProtoReflect() protoreflect.Message

func (*Document) Reset 

func (x *Document) Reset()

func (*Document) String 

func (x *Document) String() string

func (*Document) Validate 

func (doc *Document) Validate() error

Validate verifies a shac.textproto document is valid.

type FormatterFiltering 

type FormatterFiltering int

FormatterFiltering specifies whether formatting or non-formatting checks will be filtered out. 

const (
	// AllChecks does not perform any filtering based on whether a check is a
	// formatter or not.
	AllChecks FormatterFiltering = iota
	// OnlyFormatters causes only checks marked with `formatter = True` to be
	// run.
	OnlyFormatters
	// OnlyNonFormatters causes only checks *not* marked with `formatter = True` to
	// be run.
	OnlyNonFormatters
)

type Known 

type Known struct {
	Url  string           `protobuf:"bytes,1,opt,name=url,proto3" json:"url,omitempty"`
	Seen []*VersionDigest `protobuf:"bytes,2,rep,name=seen,proto3" json:"seen,omitempty"`
	// contains filtered or unexported fields
}

Known is the multiple known digests of a single dependency.

func (*Known) Descriptor deprecated 

func (*Known) Descriptor() ([]byte, []int)

Deprecated: Use Known.ProtoReflect.Descriptor instead.

func (*Known) GetSeen 

func (x *Known) GetSeen() []*VersionDigest

func (*Known) GetUrl 

func (x *Known) GetUrl() string

func (*Known) ProtoMessage 

func (*Known) ProtoMessage()

func (*Known) ProtoReflect 

func (x *Known) ProtoReflect() protoreflect.Message

func (*Known) Reset 

func (x *Known) Reset()

func (*Known) String 

func (x *Known) String() string

func (*Known) Validate 

func (k *Known) Validate() error

Validate verifies a shac.textproto sum known block is valid.

type Level 

type Level string

Level is one of "notice", "warning" or "error".

A check is only considered failed if it emits at least one finding with level "error". 

const (
	Notice  Level = "notice"
	Warning Level = "warning"
	Error   Level = "error"
	Nothing Level = ""
)

Valid Level values.

func (*Level) Set 

func (l *Level) Set(value string) error

func (*Level) String 

func (l *Level) String() string

func (*Level) Type 

func (l *Level) Type() string

type Options 

type Options struct {
	// Report gets all the emitted findings and artifacts from the checks.
	//
	// This is the only required argument. It is recommended to use
	// reporting.Get() which returns the right implementation based on the
	// environment (CI, interactive, etc).
	Report Report
	// Dir overrides the current working directory, making shac behave as if it
	// was run in the specified directory. It defaults to the current working
	// directory.
	Dir string
	// Files lists specific files to analyze.
	Files []string
	// AllFiles tells to consider all files as affected.
	AllFiles bool
	// Recurse tells the engine to run all Main files found in subdirectories.
	Recurse bool
	// Filter controls which checks run.
	Filter CheckFilter
	// Vars contains the user-specified runtime variables and their values.
	Vars map[string]string
	// EntryPoint is the main source file to run. Defaults to shac.star.
	EntryPoint string
	// contains filtered or unexported fields
}

Options is the options for Run().

type PackageManager 

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

PackageManager manages dependencies, both fetching and verifying the hashes.

func NewPackageManager 

func NewPackageManager(tmp string) *PackageManager

NewPackageManager returns an initialized PackageManager.

func (*PackageManager) RetrievePackages 

func (p *PackageManager) RetrievePackages(ctx context.Context, root string, doc *Document) (map[string]fs.FS, error)

RetrievePackages retrieve all the packages in parallel, up to 8 threads.

type PassthroughEnv 

type PassthroughEnv struct {

	// The name of the environment variable, e.g. "FOO".
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// Whether the environment variable's value is a file path that sandboxed
	// processes should be granted access to.
	IsPath bool `protobuf:"varint,2,opt,name=is_path,json=isPath,proto3" json:"is_path,omitempty"`
	// If is_path is true, whether to mount the file/directory as writeable.
	Writeable bool `protobuf:"varint,3,opt,name=writeable,proto3" json:"writeable,omitempty"`
	// contains filtered or unexported fields
}

PassthroughEnv specifies an environment variable that should be passed through into the sandbox.

func (*PassthroughEnv) Descriptor deprecated 

func (*PassthroughEnv) Descriptor() ([]byte, []int)

Deprecated: Use PassthroughEnv.ProtoReflect.Descriptor instead.

func (*PassthroughEnv) GetIsPath 

func (x *PassthroughEnv) GetIsPath() bool

func (*PassthroughEnv) GetName 

func (x *PassthroughEnv) GetName() string

func (*PassthroughEnv) GetWriteable 

func (x *PassthroughEnv) GetWriteable() bool

func (*PassthroughEnv) ProtoMessage 

func (*PassthroughEnv) ProtoMessage()

func (*PassthroughEnv) ProtoReflect 

func (x *PassthroughEnv) ProtoReflect() protoreflect.Message

func (*PassthroughEnv) Reset 

func (x *PassthroughEnv) Reset()

func (*PassthroughEnv) String 

func (x *PassthroughEnv) String() string

type Report 

type Report interface {
	// EmitFinding emits a finding by a check for a specific file. This is not a
	// failure by itself, unless level "error" is used.
	EmitFinding(ctx context.Context, check string, level Level, message, root, file string, s Span, replacements []string) error
	// EmitArtifact emits an artifact by a check.
	//
	// Only one of root or content can be specified. If root is specified, it is
	// a file on disk. The file may disappear after this function is called. If
	// root is not specified, content is the artifact. Either way, file is the
	// display name of the artifact.
	//
	// content must not be modified.
	EmitArtifact(ctx context.Context, check, root, file string, content []byte) error
	// CheckCompleted is called when a check is completed.
	//
	// It is called with the start time, wall clock duration, the highest level emitted and an error
	// if an abnormal error occurred.
	CheckCompleted(ctx context.Context, check string, start time.Time, d time.Duration, r Level, err error)
	// Print is called when print() starlark function is called.
	Print(ctx context.Context, check, file string, line int, message string)
}

Report exposes callbacks that the engine calls for everything generated by the starlark code.

type Requirements 

type Requirements struct {

	// direct are packages referenced by the starlark code via a load() statement.
	Direct []*Dependency `protobuf:"bytes,1,rep,name=direct,proto3" json:"direct,omitempty"`
	// indirect are packages referenced by direct dependencies or transitively.
	Indirect []*Dependency `protobuf:"bytes,2,rep,name=indirect,proto3" json:"indirect,omitempty"`
	// contains filtered or unexported fields
}

Requirements lists all the external dependencies, both direct and transitive (indirect).

func (*Requirements) Descriptor deprecated 

func (*Requirements) Descriptor() ([]byte, []int)

Deprecated: Use Requirements.ProtoReflect.Descriptor instead.

func (*Requirements) GetDirect 

func (x *Requirements) GetDirect() []*Dependency

func (*Requirements) GetIndirect 

func (x *Requirements) GetIndirect() []*Dependency

func (*Requirements) ProtoMessage 

func (*Requirements) ProtoMessage()

func (*Requirements) ProtoReflect 

func (x *Requirements) ProtoReflect() protoreflect.Message

func (*Requirements) Reset 

func (x *Requirements) Reset()

func (*Requirements) String 

func (x *Requirements) String() string

type Span 

type Span struct {
	// Start is the beginning of the span. If Col is specified, Line must be
	// specified.
	Start Cursor
	// End is the end of the span. If not specified, the span has only one line.
	// If Col is specified, Start.Col must be specified too. It is inclusive.
	// That is, it is impossible to do a 0 width span.
	End Cursor
	// contains filtered or unexported fields
}

Span represents a section in a source file or a change description.

type Sum 

type Sum struct {
	Known []*Known `protobuf:"bytes,1,rep,name=known,proto3" json:"known,omitempty"`
	// contains filtered or unexported fields
}

Sum is the digest of known dependencies.

func (*Sum) Descriptor deprecated 

func (*Sum) Descriptor() ([]byte, []int)

Deprecated: Use Sum.ProtoReflect.Descriptor instead.

func (*Sum) Digest 

func (s *Sum) Digest(url, version string) string

Digest returns the digest for the specified url and version.

func (*Sum) GetKnown 

func (x *Sum) GetKnown() []*Known

func (*Sum) ProtoMessage 

func (*Sum) ProtoMessage()

func (*Sum) ProtoReflect 

func (x *Sum) ProtoReflect() protoreflect.Message

func (*Sum) Reset 

func (x *Sum) Reset()

func (*Sum) String 

func (x *Sum) String() string

type Var 

type Var struct {

	// name is the name of the variable, as specified on the command line and as
	// passed into `ctx.vars.get()`.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// desc is an optional description of the meaning of the variable.
	Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"`
	// default is the default value of the variable. It may be left unspecified,
	// in which case the default is the empty string.
	Default string `protobuf:"bytes,3,opt,name=default,proto3" json:"default,omitempty"`
	// contains filtered or unexported fields
}

Var specifies a variable that may be passed into checks at runtime by the --var flag and accessed via `ctx.vars.get(name)`.

Vars are intentionally limited in usefulness so they can only be used for passing through opaque configuration strings, not for controlling behavior, which would introduce the potential for divergence between environments.

func (*Var) Descriptor deprecated 

func (*Var) Descriptor() ([]byte, []int)

Deprecated: Use Var.ProtoReflect.Descriptor instead.

func (*Var) GetDefault 

func (x *Var) GetDefault() string

func (*Var) GetDescription 

func (x *Var) GetDescription() string

func (*Var) GetName 

func (x *Var) GetName() string

func (*Var) ProtoMessage 

func (*Var) ProtoMessage()

func (*Var) ProtoReflect 

func (x *Var) ProtoReflect() protoreflect.Message

func (*Var) Reset 

func (x *Var) Reset()

func (*Var) String 

func (x *Var) String() string

type VersionDigest 

type VersionDigest struct {

	// version is one of the version referred to directly or transitively.
	Version string `protobuf:"bytes,1,opt,name=version,proto3" json:"version,omitempty"`
	// digest is the hash of the content of the dependency. It uses the same
	// hashing algorithm than go.sum. See https://golang.org/x/mod/sumdb/dirhash.
	Digest string `protobuf:"bytes,2,opt,name=digest,proto3" json:"digest,omitempty"`
	// contains filtered or unexported fields
}

VersionDigest is a version:digest pair.

func (*VersionDigest) Descriptor deprecated 

func (*VersionDigest) Descriptor() ([]byte, []int)

Deprecated: Use VersionDigest.ProtoReflect.Descriptor instead.

func (*VersionDigest) GetDigest 

func (x *VersionDigest) GetDigest() string

func (*VersionDigest) GetVersion 

func (x *VersionDigest) GetVersion() string

func (*VersionDigest) ProtoMessage 

func (*VersionDigest) ProtoMessage()

func (*VersionDigest) ProtoReflect 

func (x *VersionDigest) ProtoReflect() protoreflect.Message

func (*VersionDigest) Reset 

func (x *VersionDigest) Reset()

func (*VersionDigest) String 

func (x *VersionDigest) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.