Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 12 additions & 3 deletions cmd/taskgate/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,11 @@
// CI does is written once, in the Taskfile, a developer runs the same thing, and what decides
// anything is Go with a test:
//
// go tool taskgate [-allow file] [-task path] [-max-lines n] [-max-script-lines n] [dir]
// go tool taskgate [-allow file] [-task path] [-command cmd]... [-max-lines n] [-max-script-lines n] [dir]
//
// -command is a command of the repository's own that a step may be instead of a task, as it is
// spelled at the start of the step - `go run ./cmd/spin-os`, or `spin-os` where a step put it on
// the PATH - one flag each. A step that runs it runs it once and nothing else, as a task's does.
//
// -allow names what is allowed on purpose, one `<key> # why` a line: a step as
// `<file>/<job>/<step>` (a composite action's without the job), a Taskfile's block as
Expand All @@ -28,6 +32,11 @@ func main() {
task := flag.String("task", "task", "the Task binary that lists the Taskfile's tasks")
maxLines := flag.Int("max-lines", 12, "lines of shell a task's own cmd or sh may hold; 0 is any")
maxScript := flag.Int("max-script-lines", 40, "lines of shell a script a task runs may hold; 0 is any")
var commands []string
flag.Func("command", "a command of the repository's own a step may be instead of a task (repeatable)", func(c string) error {
commands = append(commands, c)
return nil
})
flag.Parse()
root := "."
if flag.NArg() > 0 {
Expand All @@ -43,7 +52,7 @@ func main() {
fmt.Fprintln(os.Stderr, err)
os.Exit(2)
}
findings, err := taskgate.Check(root, taskgate.Limits{Block: *maxLines, Script: *maxScript}, known)
findings, err := taskgate.Check(root, taskgate.Limits{Block: *maxLines, Script: *maxScript}, known, commands...)
if err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(2)
Expand All @@ -59,5 +68,5 @@ func main() {
fmt.Printf("taskgate: %d finding(s), %d stale exemption(s)\n", len(unexplained), len(stale))
os.Exit(1)
}
fmt.Printf("OK: every workflow step runs a task the Taskfile has, and every task is commands (%d exempt).\n", len(allowed))
fmt.Printf("OK: every workflow step runs a task the Taskfile has or one of the repository's commands, and every task is commands (%d exempt).\n", len(allowed))
}
38 changes: 27 additions & 11 deletions internal/taskgate/taskgate.go
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ func (s Step) Key() string {
}

func (s Step) String() string {
return fmt.Sprintf("%s:%d: step %q runs %q: a step is one `task <name>`, and what it does is that task in the Taskfile, where a developer runs it too",
return fmt.Sprintf("%s:%d: step %q runs %q: a step is one `task <name>`, or one of the repository's own commands (-command), which a developer runs too",
s.File, s.Line, s.Step, s.Run)
}

Expand Down Expand Up @@ -84,8 +84,9 @@ type Limits struct {
// Check is every finding under root: in the workflows and composite actions, the Taskfiles and
// the scripts their tasks run - what git lists, tracked or untracked and not ignored. known is
// every name the root's Taskfile answers to (Tasks); a step naming another is Missing. Nil asks
// nothing of the names.
func Check(root string, limits Limits, known map[string]bool) ([]Finding, error) {
// nothing of the names. commands are the repository's own commands a step may be instead of a
// task (`go run ./cmd/spin-os`, `spin-os`): one invocation of one of them, as a task is one.
func Check(root string, limits Limits, known map[string]bool, commands ...string) ([]Finding, error) {
out, err := exec.Command("git", "-C", root, "ls-files", "--cached", "--others", "--exclude-standard").Output()
if err != nil {
return nil, fmt.Errorf("taskgate: listing %s: %w", root, err)
Expand All @@ -107,7 +108,7 @@ func Check(root string, limits Limits, known map[string]bool) ([]Finding, error)
if err != nil {
return nil, err
}
found, calls, err := steps(rel, raw)
found, calls, err := steps(rel, raw, commands)
if err != nil {
return nil, fmt.Errorf("taskgate: %s: %w", rel, err)
}
Expand Down Expand Up @@ -149,20 +150,20 @@ func workflow(rel string) bool {

// steps is the findings of one file - a workflow's jobs' steps, or a composite action's - and
// each task a step that is one task names, for Check to look up.
func steps(rel string, raw []byte) ([]Step, []Missing, error) {
func steps(rel string, raw []byte, commands []string) ([]Step, []Missing, error) {
top, err := document(raw)
if err != nil || top == nil {
return nil, nil, err
}
var out []Step
var calls []Missing
if runs := field(top, "runs"); runs != nil {
found, named := judge(rel, "", field(runs, "steps"))
found, named := judge(rel, "", field(runs, "steps"), commands)
out, calls = append(out, found...), append(calls, named...)
}
if jobs := field(top, "jobs"); jobs != nil && jobs.Kind == yaml.MappingNode {
for i := 0; i+1 < len(jobs.Content); i += 2 {
found, named := judge(rel, jobs.Content[i].Value, field(jobs.Content[i+1], "steps"))
found, named := judge(rel, jobs.Content[i].Value, field(jobs.Content[i+1], "steps"), commands)
out, calls = append(out, found...), append(calls, named...)
}
}
Expand All @@ -185,7 +186,7 @@ func document(raw []byte) (*yaml.Node, error) {
}

// judge is the findings of one job's steps, and the tasks its steps that are one task name.
func judge(rel, job string, steps *yaml.Node) ([]Step, []Missing) {
func judge(rel, job string, steps *yaml.Node, commands []string) ([]Step, []Missing) {
if steps == nil || steps.Kind != yaml.SequenceNode {
return nil, nil
}
Expand All @@ -211,6 +212,9 @@ func judge(rel, job string, steps *yaml.Node) ([]Step, []Missing) {
}
continue
}
if len(lines) == 1 && isCommand(lines[0].Text, commands) {
continue
}
at.Run = strings.TrimSpace(run.Value)
if len(lines) > 0 {
at.Run = lines[0].Text
Expand Down Expand Up @@ -256,11 +260,23 @@ func firstLine(n *yaml.Node) int {
// with what it is given.
func isTask(line string) bool {
line = strings.TrimPrefix(line, "go tool ")
if !strings.HasPrefix(line+" ", "task ") {
return false
return strings.HasPrefix(line+" ", "task ") && alone(line)
}

// isCommand is a line that runs one of the repository's own commands and nothing else, with what
// it is given: the command is the program a developer runs too, as a task is.
func isCommand(line string, commands []string) bool {
for _, c := range commands {
if strings.HasPrefix(line+" ", c+" ") && alone(line) {
return true
}
}
return false
}

// alone is a line that is one command: a second one after it is shell around the command.
func alone(line string) bool {
for w := range strings.FieldsSeq(line) {
// One command: a second one after it is shell around the task, not the task.
if w == "&&" || w == "||" || w == ";" || w == "|" || strings.HasPrefix(w, ">") {
return false
}
Expand Down
32 changes: 32 additions & 0 deletions internal/taskgate/taskgate_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -170,3 +170,35 @@ echo '{"tasks":[{"name":"lint","aliases":["l"]},{"name":"e2e:up","aliases":[]}]}
})
}
}

// A step may be one of the repository's own commands instead of a task, given with what it takes;
// the same command with shell around it, a command that only begins like one, or a command not
// named is a Step as any other shell is.
func TestAStepMayBeTheRepositorysOwnCommand(t *testing.T) {
root := repo(t, map[string]string{
".github/workflows/ci.yml": `on: push
jobs:
gate:
steps:
- run: go run ./cmd/spin-os upgrade --propose
- run: spin-os build runner --secureboot ${{ inputs.sb }}
- run: spin-os
- run: go run ./cmd/spin-os scan | tee out
- run: spin-osx build
- run: go run ./cmd/other build
`,
})
findings, err := taskgate.Check(root, taskgate.Limits{}, nil, "go run ./cmd/spin-os", "spin-os")
require.NoError(t, err)
var got []string
for _, f := range findings {
got = append(got, f.Key())
}
assert.ElementsMatch(t, []string{
".github/workflows/ci.yml/gate/#4",
".github/workflows/ci.yml/gate/#5",
".github/workflows/ci.yml/gate/#6",
}, got)
require.NotEmpty(t, findings)
assert.Contains(t, findings[0].String(), "one of the repository's own commands (-command)")
}
16 changes: 15 additions & 1 deletion site/src/content/docs/taskgate.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ lines, and the scripts a task calls to being scripts - a program that *decides*
what it reads has an answer a test could hold, and belongs in Go.

```sh
go tool taskgate [-allow file] [-task path] [-max-lines n] [-max-script-lines n] [dir]
go tool taskgate [-allow file] [-task path] [-command cmd]... [-max-lines n] [-max-script-lines n] [dir]
```

## What a step looks like
Expand Down Expand Up @@ -47,6 +47,20 @@ A step passes when its `run:` is a single `task ...` or `go tool task ...` line,
arguments and variables it is given. It fails on a second line, on `&&`, `||`, `;` or `|` after the
task, and on output redirected with `>`.

## Or the repository's own command

A repository whose interface is a command of its own - spin-ami's `spin-os build`, `spin-os
upgrade` - names it with `-command`, one flag for each way a step spells it:

```sh
go tool taskgate -command "go run ./cmd/spin-os" -command spin-os
```

A step that is one invocation of it passes as a task does: the same command a developer types,
whose logic is Go with tests. The rule is the task's: one command, with nothing around it - a `|`,
`&&` or `>` after it is a finding. The verb it names is not looked up: the command refuses one it
does not have, the first time the step runs.

## The task is one the Taskfile has

A step that is one task must name a task the Taskfile has. actionlint resolves a job's `needs:`
Expand Down
Loading