diff --git a/cmd/taskgate/main.go b/cmd/taskgate/main.go index e72629f..8e7b195 100644 --- a/cmd/taskgate/main.go +++ b/cmd/taskgate/main.go @@ -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 ` # why` a line: a step as // `//` (a composite action's without the job), a Taskfile's block as @@ -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 { @@ -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) @@ -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)) } diff --git a/internal/taskgate/taskgate.go b/internal/taskgate/taskgate.go index 4c563a0..9b751cb 100644 --- a/internal/taskgate/taskgate.go +++ b/internal/taskgate/taskgate.go @@ -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 `, 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 `, or one of the repository's own commands (-command), which a developer runs too", s.File, s.Line, s.Step, s.Run) } @@ -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) @@ -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) } @@ -149,7 +150,7 @@ 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 @@ -157,12 +158,12 @@ func steps(rel string, raw []byte) ([]Step, []Missing, error) { 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...) } } @@ -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 } @@ -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 @@ -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 } diff --git a/internal/taskgate/taskgate_test.go b/internal/taskgate/taskgate_test.go index f521caf..01f016a 100644 --- a/internal/taskgate/taskgate_test.go +++ b/internal/taskgate/taskgate_test.go @@ -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)") +} diff --git a/site/src/content/docs/taskgate.md b/site/src/content/docs/taskgate.md index cc83505..ec2788b 100644 --- a/site/src/content/docs/taskgate.md +++ b/site/src/content/docs/taskgate.md @@ -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 @@ -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:`