The highest tagged major version is
Documentation
¶
Overview ¶
Package invoke runs an analyzer as a separate process: Describe runs its describe verb and admits or refuses the analyzer from what it prints, and Analyze runs its analyze verb and reads the report the analyzer writes to the file the invocation names. No analyzer is linked into this program as a library.
The read is fail-closed. The exit code is read before the report is opened, and only a code that is a verdict about a complete report lets the report be read at all. An absent report, a report that does not decode, and a cancelled run each leave the run with no report from that analyzer, and Run then returns no report from any analyzer. Every refusal of a read is an *Error naming the provider entry and the report path, and every refusal of a handshake a *HandshakeError naming the provider entry and its command; the exit code the run returns for one is the caller's to decide.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrDescribeExited reports a describe verb that exited with a code other // than 0, so what it printed is not read. ErrDescribeExited = errors.New("describe did not describe the analyzer") // ErrDescription reports a describe document the handshake cannot read. ErrDescription = errors.New("describe printed no document the handshake reads") // ErrNoConformancePass reports an analyzer whose describe document records // no conformance record, or a result other than pass. ErrNoConformancePass = errors.New("the analyzer records no conformance pass") // ErrSchemaVersion reports an analyzer that reads no report schema version // the run accepts. ErrSchemaVersion = errors.New("the analyzer reads no schema version the run accepts") // ErrDescribedName reports an analyzer that describes itself under a name // other than its provider entry's. ErrDescribedName = errors.New("the analyzer describes itself under another name than its provider entry's") )
The refusals a handshake makes, each carried by a *HandshakeError.
var ( // ErrExited reports an analyzer whose exit code is not a verdict about a // complete report, so whatever the report path holds is not read. ErrExited = errors.New("the exit code carries no report") // ErrNoReport reports an analyzer that exited with a verdict and wrote no // report. ErrNoReport = errors.New("the analyzer wrote no report") // ErrReportExists reports a file already at the report path, which no read // could tell from a report the analyzer wrote; the analyzer is not run. ErrReportExists = errors.New("a file is at the report path before the analyzer ran") // ErrUnresolvedCommand reports a request whose command is not an absolute // path, which running would look up on PATH; neither verb runs it, and a // handshake carries it in a [*HandshakeError]. ErrUnresolvedCommand = errors.New("the command is not the absolute path provider selection resolves") )
The refusals an invocation makes, each carried by an *Error.
Functions ¶
func Analyze ¶
Analyze runs the analyze verb of the analyzer req names and reads the report it wrote. It returns the report and the analyzer's exit code, or no report and an *Error.
func Run ¶
Run analyzes every request at once, each as its own process, and returns every report in the order of the requests. What each analyzer prints is held until every analyzer has exited and then written to its request's Diagnostics whole, the requests ordered by analyzer name, so two analyzers' lines never interleave. When any request leaves no report, it returns no report at all and an error joining every *Error in request order, so no analyzer's findings stand as the run's result beside another's failure. A setup failure's lines are followed by the [workaround] line.
Types ¶
type Description ¶ added in v1.2.3
type Description struct {
// Conformance is the analyzer's result over the conformance corpus, or nil
// where the document states none.
Conformance *report.Conformance
Name string
Version string
ContractVersion string
// SchemaVersionsAccepted is every report schema version the analyzer reads.
SchemaVersionsAccepted []string
// Languages is the languages the analyzer claims.
Languages []string
}
Description is what an analyzer's describe verb states about it.
func Describe ¶ added in v1.2.3
func Describe(ctx context.Context, req *Request, kept rundir.Entry, accepted []string) (*Description, error)
Describe runs the describe verb of req.Command before any analysis, keeps what it printed at kept's describe file, a command that never started keeping nothing, and reads the document. It admits the analyzer, returning the description, when the document names the provider entry's name, records a conformance pass and reads one of the accepted report schema versions; otherwise it returns a *HandshakeError. The verb's stderr goes to req.Diagnostics, and the scope, configuration and report paths are not read.
type Error ¶
type Error struct {
// Err is what went wrong: [ErrExited], [ErrNoReport], [ErrReportExists],
// a [*report.Error] naming the value at fault and why, the cause of a
// cancelled run, or the error the analyzer could not be run or read with.
Err error
Analyzer string // the provider entry
Report string // the report path
// Exit is the analyzer's exit code, or -1 when it did not run or did not
// exit on its own.
Exit int
}
Error is an invocation that left no report the run may read.
type HandshakeError ¶ added in v1.2.3
type HandshakeError struct {
// Err is what went wrong: one of the refusals this package declares for a
// handshake, the cause of a cancelled run, or the error the analyzer could
// not be run with or what it printed could not be kept with.
Err error
Analyzer string // the provider entry
Command string // the executable the provider entry's command resolved to
// Exit is the describe verb's exit code, or -1 when it did not run or did
// not exit on its own.
Exit int
}
HandshakeError is a handshake that admitted no analyzer.
func (*HandshakeError) Error ¶ added in v1.2.3
func (e *HandshakeError) Error() string
Error renders the refusal as one line naming the entry and its command.
func (*HandshakeError) Unwrap ¶ added in v1.2.3
func (e *HandshakeError) Unwrap() error
Unwrap is the refusal's cause.
type Request ¶
type Request struct {
// Diagnostics receives everything the analyzer prints, on stderr and on
// the stdout the contract leaves empty. A nil Diagnostics discards it.
Diagnostics io.Writer
// Analyzer is the name of the provider entry, which every refusal names.
Analyzer string
// Command is the absolute path of the analyzer's executable, as provider
// selection resolved it. Nothing here looks a command up again, so the file
// the handshake ran is the file the analysis runs.
Command string
// Dir is the directory the analyzer runs in, which a report names its
// paths relative to. An empty Dir is this process's working directory.
Dir string
Scope string // the scope document, passed as --scope
Config string // the analyzer's configuration, passed as --config
Report string // where the analyzer writes its report, passed as --report
// Languages are the languages of the target the run hands the analyzer.
Languages []string
}
Request is one analyze invocation: the provider entry it runs, and the three paths the analyzer CLI contract passes.
Source Files