diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index d7f303c..51732bc 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -50,8 +50,7 @@ jobs: - uses: powerman/.github/.github/actions/cache-go-and-tools@main - run: mise run scripts:test - - run: mise run toc --check - - run: mise run lint:links + - run: mise run lint:docs # Testing on available native platforms. # Go scripts don't need mise: they are built and run by Go alone. @@ -66,6 +65,7 @@ jobs: runs-on: ${{ matrix.os }} timeout-minutes: 10 env: + SCRIPTS_BIN: ${{ github.workspace }}/.cache/scripts KONGUSAGE_TEST_SKIP_USAGE: 1 # Tool usage of mise.toml is not installed here. defaults: run: @@ -84,9 +84,8 @@ jobs: - run: go -C scripts test -timeout=60s ./... if: matrix.os == 'windows-11-arm' - - run: go -C scripts build -o ../.cache/bin/ ./... - - run: .cache/bin/toc --check - - run: .cache/bin/lint-links + - run: go -C scripts build -o "$SCRIPTS_BIN/" ./... + - run: '"$SCRIPTS_BIN/lint-docs"' # Testing on available docker QEMU platforms (Linux only). qemu: @@ -124,13 +123,13 @@ jobs: -v "$HOME/.cache/go-build:/root/.cache/go-build" \ -v "$HOME/go:/go" \ -e KONGUSAGE_TEST_SKIP_USAGE=1 \ + -e SCRIPTS_BIN=/workspace/.cache/scripts \ "golang:${V}-alpine" sh -e -c ' apk add --no-cache git >/dev/null git config --global --add safe.directory /workspace go -C scripts test -timeout=60s ./... - go -C scripts build -o ../.cache/bin/ ./... - .cache/bin/toc --check - .cache/bin/lint-links + go -C scripts build -o "$SCRIPTS_BIN/" ./... + "$SCRIPTS_BIN/lint-docs" ' # The same as qemu, but by task test-qemu, which can also be run locally. diff --git a/README.md b/README.md index 30a8b84..58c1a01 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,8 @@ copy the parts you need and adapt them. The scripts here are real tasks of this repository: [toc](scripts/toc/) maintains the table of contents below, -[lint:links](scripts/lint-links/) checks links in markdown files on CI, +[lint:docs](scripts/lint-docs/) checks it and links in markdown files +by `toc --check` and [lint-links](scripts/lint-links/) on CI, on Linux, macOS and Windows, and [test-qemu](scripts/test-qemu/) tests scripts in docker on platforms emulated by QEMU. @@ -32,6 +33,7 @@ and [test-qemu](scripts/test-qemu/) tests scripts in docker on platforms emulate - [Why mise](#why-mise) - [A separate Go module](#a-separate-go-module) - [Build on demand](#build-on-demand) + - [Running binaries](#running-binaries) - [Completion](#completion) - [Code of a script](#code-of-a-script) - [Tests: Fake for World, Mock for App](#tests-fake-for-world-mock-for-app) @@ -85,10 +87,12 @@ so a Go script is as convenient to run as a shell script. ## What this example shows -- Two scripts which process files, [toc](scripts/toc/) and [lint:links](scripts/lint-links/), +- Two scripts which process files, [toc](scripts/toc/) and [lint-links](scripts/lint-links/), with code shared in [scripts/internal/markdown](scripts/internal/markdown/). - A script which orchestrates external commands, [test-qemu](scripts/test-qemu/): it has little logic and a `World` which runs docker. +- A script which runs binaries of other scripts, [lint:docs](scripts/lint-docs/): + it finds them by `$SCRIPTS_BIN`, like tasks do, without a nested `mise run`. - Scripts as mise tasks: a fast rebuild on demand, completion of flags and arguments, tasks to build, generate, format, lint, test and cover scripts. - A layout of a script which makes it testable: @@ -99,7 +103,7 @@ so a Go script is as convenient to run as a shell script. and [kongusage](https://github.com/powerman/kongusage) for its completion in mise. - [bitfield/script](https://github.com/bitfield/script) to run commands, so an adapter looks almost like a shell command: - [toc](scripts/toc/internal/world.go), [lint:links](scripts/lint-links/internal/world.go), + [toc](scripts/toc/internal/world.go), [lint-links](scripts/lint-links/internal/world.go), [test-qemu](scripts/test-qemu/internal/world.go). - Scripts used by tasks of the project ([fmt and lint](mise.toml)) and run on CI. - Scripts run on [CI](.github/workflows/test.yml) on Linux, macOS and Windows: @@ -121,7 +125,8 @@ so a Go script is as convenient to run as a shell script. ├── .mockery/ Template of fakes. ├── internal/ │ └── markdown/ Code shared by scripts. - ├── lint-links/ Program of task lint:links. + ├── lint-docs/ Program of task lint:docs. + ├── lint-links/ Program without a task, run by lint-docs. ├── test-qemu/ Program of task test-qemu. └── toc/ Program of task toc. ├── main.go Parses the CLI and runs it. @@ -147,7 +152,7 @@ mise install ```sh mise run toc --help mise run toc --check README.md -mise run lint:links +mise run lint:docs mise run test-qemu linux/arm/v7 linux/riscv64 ``` @@ -155,8 +160,9 @@ Arguments are passed to the script as is, `--help` and invalid flags included. Flags and arguments of a task are completed by Tab when [completion of mise](https://mise.jdx.dev/cli/completion.html) is enabled. -A program is in `.cache/bin/` and may be run directly, -but it may be outdated: run `mise run scripts:build` first. +Binaries of scripts are built into `.cache/scripts/`, +but run them by tasks: +a task rebuilds a binary before the run and completes its arguments. ### Develop scripts @@ -220,11 +226,11 @@ description = 'Update tables of contents in markdown files' depends = ['scripts:build'] usage = 'mount run="mise run -q toc --usage-spec"' raw_args = true -run = '.cache/bin/toc' -run_windows = '.cache\bin\toc' +run = '"${SCRIPTS_BIN:?}/toc"' +run_windows = '"%SCRIPTS_BIN%\toc"' ``` -- `scripts:build` rebuilds all programs into `.cache/bin/` +- `scripts:build` rebuilds binaries of all programs into `$SCRIPTS_BIN` only when files of `scripts/` change (by `sources` and `outputs`), so a start of a task takes a few milliseconds. `go run` isn't used: its own check of changes takes much longer. @@ -234,6 +240,32 @@ run_windows = '.cache\bin\toc' so an argument `--` needs `mise run toc -- -- …`. - A program of task `` is `scripts//`, with `:` in the name replaced by `-`. The binary is named by its directory, so `kong.Name` sets the task name for help. +- A binary which only tasks and other binaries run has no task: + a task is needed only to run a binary by hand. + +### Running binaries + +[mise.toml](mise.toml) gives every task and binary the directory of binaries: + +```toml +[env] +SCRIPTS_BIN = '{{config_root}}/.cache/scripts' # Go scripts built by scripts:build. +``` + +Tasks and binaries find binaries only by this variable, +so it works from any directory, and the path is written in one place. + +- A task which runs a binary depends on `scripts:build` and runs `"${SCRIPTS_BIN:?}/"`. +- A binary runs another binary by `filepath.Join(os.Getenv("SCRIPTS_BIN"), "")` + ([lint-docs](scripts/lint-docs/internal/world.go)), + without a build: the task which started it has built all binaries. +- A binary isn't run by a nested `mise run`: + mise resolves tools and env for each task it runs, + so a nested `mise run` takes about 100 ms against about 3 ms of a direct start, + and mise adds `ERROR task failed` to the output on any non-zero exit status. +- `$SCRIPTS_BIN` isn't added to `PATH`: + binaries have short common names and would shadow commands of the system + in tasks and in the shell activated by mise. ### Completion @@ -252,7 +284,7 @@ type CLI struct { mise does it only on Tab, so the spec is never stale, and a broken spec breaks completion of only this task. A test checks the spec by `kongusage.CheckSpec`, -and `scripts:lint:usage` lints specs of all programs. +and `scripts:lint:usage` lints specs of all binaries. ### Code of a script @@ -323,17 +355,18 @@ With bitfield/script: Go scripts work on Windows, but mise tasks around them need care: -- mise runs inline scripts by `cmd /c` on Windows, which can't run `.cache/bin/toc`, - so a task which runs a program has `run_windows = '.cache\bin\toc'`. +- mise runs inline scripts by `cmd /c` on Windows, which doesn't expand `$SCRIPTS_BIN`, + so a task which runs a binary has `run_windows = '"%SCRIPTS_BIN%\toc"'`. - Tasks needed to run scripts (`scripts:build`, `scripts:build:clean`, `scripts:test`) - work in cmd too, with PowerShell in `run_windows` where POSIX sh is needed. + work in cmd too, with `run_windows` where they use sh: + `%SCRIPTS_BIN%` instead of `$SCRIPTS_BIN`, PowerShell instead of a loop. Other tasks to develop scripts need POSIX sh (e.g. Git Bash). - Some tools of `mise.toml` may be unavailable on Windows, so [CI](.github/workflows/test.yml) installs only tools of scripts (`install_args` of `jdx/mise-action`) and sets `MISE_AUTO_INSTALL=false`, so `mise run` doesn't try to install others. - Git returns paths with `/`, while arguments may use `\`: - [lint:links](scripts/lint-links/internal/app.go) converts them by `filepath.ToSlash`. + [lint-links](scripts/lint-links/internal/app.go) converts them by `filepath.ToSlash`. ## Add Go scripts to your project @@ -351,7 +384,7 @@ This repository is such a project. Copy: and [scripts/.mockery/](scripts/.mockery/); - `scripts/go.mod` with your module path, e.g. `github.com/you/project/scripts`; - from [mise.toml](mise.toml): `[task_config]`, tools of Go scripts, - `vars.scripts_cover`, tasks `bump` and `cachedir`, + `env.SCRIPTS_BIN`, `vars.scripts_cover`, tasks `bump` and `cachedir`, and `scripts:*` tasks in root tasks `generate`, `fmt`, `lint` and `test`. ### A project in Go @@ -371,8 +404,8 @@ The same, with a few differences: **What exactly is the approach here?** Only the task layer: -root mise tasks which build Go CLIs on demand into `.cache/bin` -and complete their flags and arguments. +root mise tasks which build Go CLIs on demand into `$SCRIPTS_BIN`, +run them directly and complete their flags and arguments. Everything about the Go code itself is outside the approach: its structure, [libraries](#libraries), code generators and linter config. This example shows one recommended way to write and test it. diff --git a/mise.toml b/mise.toml index 65d1451..6c18618 100644 --- a/mise.toml +++ b/mise.toml @@ -50,6 +50,7 @@ gh = 'latest' [env] +SCRIPTS_BIN = '{{config_root}}/.cache/scripts' # Go scripts built by scripts:build. PNPM_CONFIG_VIRTUAL_STORE_TYPE = 'project' # Fixed in 2026.11.1, remove after updating min_version. @@ -137,13 +138,13 @@ run = "git ls-files -z -co --exclude-standard '*.yml' '*.yaml' | xargs -0 -r yam description = 'Lint GitHub Action workflows' run = 'actionlint' -[tasks.'lint:links'] -description = 'Check local links in markdown files' +[tasks.'lint:docs'] +description = 'Check tables of contents and local links in markdown files' depends = ['scripts:build'] -usage = 'mount run="mise run -q lint:links --usage-spec"' +usage = 'mount run="mise run -q lint:docs --usage-spec"' raw_args = true -run = '.cache/bin/lint-links' -run_windows = '.cache\bin\lint-links' +run = '"${SCRIPTS_BIN:?}/lint-docs"' +run_windows = '"%SCRIPTS_BIN%\lint-docs"' [tasks.'lint:markdown'] description = 'Lint markdown files' @@ -171,8 +172,8 @@ description = 'Update tables of contents in markdown files' depends = ['scripts:build'] usage = 'mount run="mise run -q toc --usage-spec"' raw_args = true -run = '.cache/bin/toc' -run_windows = '.cache\bin\toc' +run = '"${SCRIPTS_BIN:?}/toc"' +run_windows = '"%SCRIPTS_BIN%\toc"' # Not test:qemu: it's slow and needs docker, so `test:*` of a project must not run it. [tasks.test-qemu] @@ -180,8 +181,8 @@ description = 'Test Go scripts on other platforms emulated by QEMU in docker' depends = ['scripts:build'] usage = 'mount run="mise run -q test-qemu --usage-spec"' raw_args = true -run = '.cache/bin/test-qemu' -run_windows = '.cache\bin\test-qemu' +run = '"${SCRIPTS_BIN:?}/test-qemu"' +run_windows = '"%SCRIPTS_BIN%\test-qemu"' [tasks.check-drift] hide = true diff --git a/scripts/.mockery.yml b/scripts/.mockery.yml index fe9d18b..e33d154 100644 --- a/scripts/.mockery.yml +++ b/scripts/.mockery.yml @@ -13,6 +13,10 @@ _anchors: filename: 'fake.{{.InterfaceFile | base | trimSuffix ".go"}}_test.go' structname: 'Fake{{.InterfaceName | firstUpper}}' packages: + github.com/powerman/go-scripts-example/scripts/lint-docs/internal: + interfaces: + World: + config: *fake github.com/powerman/go-scripts-example/scripts/lint-links/internal: interfaces: World: diff --git a/scripts/lint-docs/internal/app.go b/scripts/lint-docs/internal/app.go new file mode 100644 index 0000000..3c59eee --- /dev/null +++ b/scripts/lint-docs/internal/app.go @@ -0,0 +1,31 @@ +package internal + +import ( + "errors" + "fmt" +) + +type app struct { + world World +} + +// NewApp creates an App which uses world. +func NewApp(world World) *app { + return &app{world: world} +} + +// Check implements [App]. +func (a *app) Check() error { + checks := [][]string{ // Binaries of Go scripts with their arguments. + {"toc", "--check"}, + {"lint-links"}, + } + var errs []error + for _, c := range checks { + err := a.world.RunScript(c[0], c[1:]...) + if err != nil { + errs = append(errs, fmt.Errorf("%s: %w", c[0], err)) + } + } + return errors.Join(errs...) +} diff --git a/scripts/lint-docs/internal/app_test.go b/scripts/lint-docs/internal/app_test.go new file mode 100644 index 0000000..ad88a46 --- /dev/null +++ b/scripts/lint-docs/internal/app_test.go @@ -0,0 +1,74 @@ +package internal_test + +import ( + "errors" + "strings" + "testing" + + "github.com/powerman/check" + + "github.com/powerman/go-scripts-example/scripts/lint-docs/internal" +) + +var errRun = errors.New("stub run error") + +// newWorld returns a fake of binaries which all succeed. +func newWorld() *FakeWorld { + w := NewFakeWorld() + w.RunScriptFunc.SetDefaultReturn(nil) + return w +} + +// runs returns command lines of binaries run by w. +func runs(w *FakeWorld) []string { + history := w.RunScriptFunc.History() + lines := make([]string, 0, len(history)) + for _, c := range history { + lines = append(lines, strings.Join(append([]string{c.Name}, c.ArgArgs...), " ")) + } + return lines +} + +var allRuns = []string{"toc --check", "lint-links"} + +func TestApp_Check(tt *testing.T) { + tt.Parallel() + + tests := []struct { + name string + prepare func(*FakeWorld) + want string + }{ + { + name: "OK", + prepare: func(*FakeWorld) {}, + }, + { + name: "FirstFails", + prepare: func(w *FakeWorld) { w.RunScriptFunc.PushReturn(errRun) }, + want: "^toc: stub run error$", + }, + { + name: "AllFail", + prepare: func(w *FakeWorld) { w.RunScriptFunc.SetDefaultReturn(errRun) }, + want: "^toc: stub run error\nlint-links: stub run error$", + }, + } + for _, tc := range tests { + tt.Run(tc.name, func(tt *testing.T) { + tt.Parallel() + t := check.T(tt).MustAll() + w := newWorld() + tc.prepare(w) + + err := internal.NewApp(w).Check() + if tc.want == "" { + t.Nil(err) + } else { + t.Err(err, errRun) + t.Match(err, tc.want) + } + t.DeepEqual(runs(w), allRuns) + }) + } +} diff --git a/scripts/lint-docs/internal/cmd.go b/scripts/lint-docs/internal/cmd.go new file mode 100644 index 0000000..c277db6 --- /dev/null +++ b/scripts/lint-docs/internal/cmd.go @@ -0,0 +1,13 @@ +package internal + +import "github.com/powerman/kongusage" + +// CLI defines the command-line interface of the program. +type CLI struct { + UsageSpec kongusage.Flag +} + +// Run executes the CLI. +func (CLI) Run(a App) error { + return a.Check() +} diff --git a/scripts/lint-docs/internal/cmd_test.go b/scripts/lint-docs/internal/cmd_test.go new file mode 100644 index 0000000..a174025 --- /dev/null +++ b/scripts/lint-docs/internal/cmd_test.go @@ -0,0 +1,58 @@ +package internal_test + +import ( + "errors" + "io" + "testing" + + "github.com/alecthomas/kong" + "github.com/powerman/check" + "github.com/powerman/kongusage" + "go.uber.org/mock/gomock" + + "github.com/powerman/go-scripts-example/scripts/lint-docs/internal" +) + +var errApp = errors.New("stub app error") + +// kongRun parses args like main and runs the CLI with a. +func kongRun(t *check.C, a internal.App, args ...string) error { + t.Helper() + var cli internal.CLI + k, err := kong.New(&cli, + kong.Name("lint:docs"), + kong.Writers(io.Discard, io.Discard), + kong.Exit(func(int) {}), + ) + t.Nil(err) + ctx, err := k.Parse(args) + if err != nil { + return err + } + ctx.BindTo(a, (*internal.App)(nil)) + return ctx.Run() +} + +func TestCLI_Run(tt *testing.T) { + tt.Parallel() + t := check.T(tt).MustAll() + a := NewMockApp(gomock.NewController(t)) + a.EXPECT().Check().Return(errApp) + + err := kongRun(t, a) + t.Err(err, errApp) +} + +func TestCLI_Run_Args(tt *testing.T) { + tt.Parallel() + t := check.T(tt).MustAll() + a := NewMockApp(gomock.NewController(t)) + + err := kongRun(t, a, "README.md") + t.Match(err, `unexpected argument README.md`) +} + +func TestUsageSpec(t *testing.T) { + t.Parallel() + kongusage.CheckSpec(t, kong.Must(&internal.CLI{}, kong.Name("lint:docs"))) +} diff --git a/scripts/lint-docs/internal/fake.port_test.go b/scripts/lint-docs/internal/fake.port_test.go new file mode 100644 index 0000000..f86056d --- /dev/null +++ b/scripts/lint-docs/internal/fake.port_test.go @@ -0,0 +1,147 @@ +// Code generated by mockery; DO NOT EDIT. +// github.com/vektra/mockery +// template: fake (github.com/powerman/mockery-templates) + +package internal_test + +import ( + "sync" + + "github.com/powerman/go-scripts-example/scripts/lint-docs/internal" +) + +// FakeWorld is a fake implementation of the World interface +// (from the package github.com/powerman/go-scripts-example/scripts/lint-docs/internal) used for unit testing. +type FakeWorld struct { + // RunScriptFunc is an instance of a fake function object + // controlling the behavior of the method RunScript. + RunScriptFunc FakeWorldRunScriptFunc +} + +// NewFakeWorld creates a new fake of the World interface. +// All methods panic on invocation, unless overwritten. +func NewFakeWorld() *FakeWorld { + return &FakeWorld{} +} + +// NewFakeWorldFrom creates a new fake of the World interface. +// All methods delegate to the given implementation, unless overwritten. +func NewFakeWorldFrom(i internal.World) *FakeWorld { + return &FakeWorld{ + RunScriptFunc: FakeWorldRunScriptFunc{ + defaultHook: i.RunScript, + }, + } +} + +// FakeWorldRunScriptFunc describes the behavior when the RunScript method +// of the parent FakeWorld instance is invoked. +type FakeWorldRunScriptFunc struct { + defaultHook func(string, ...string) error + hooks []func(string, ...string) error + history []FakeWorldRunScriptFuncCall + mutex sync.Mutex +} + +// RunScript delegates to the next hook function in the queue +// and stores the parameter and result values of this invocation. +func (m *FakeWorld) RunScript(v0 string, v1 ...string) error { + r0 := m.RunScriptFunc.nextHook()(v0, v1...) + m.RunScriptFunc.appendCall(FakeWorldRunScriptFuncCall{v0, v1, r0}) + return r0 +} + +// SetDefaultHook sets function that is called when the RunScript method +// of the parent FakeWorld instance is invoked and the hook queue is empty. +func (f *FakeWorldRunScriptFunc) SetDefaultHook(hook func(string, ...string) error) { + f.defaultHook = hook +} + +// PushHook adds a function to the end of hook queue. +// Each invocation of the RunScript method of the parent FakeWorld instance +// invokes the hook at the front of the queue and discards it. +// After the queue is empty, the default hook function is invoked for any future action. +func (f *FakeWorldRunScriptFunc) PushHook(hook func(string, ...string) error) { + f.mutex.Lock() + f.hooks = append(f.hooks, hook) + f.mutex.Unlock() +} + +// SetDefaultReturn calls SetDefaultHook with a function that returns the given values. +func (f *FakeWorldRunScriptFunc) SetDefaultReturn(r0 error) { + f.SetDefaultHook(func(string, ...string) error { + return r0 + }) +} + +// PushReturn calls PushHook with a function that returns the given values. +func (f *FakeWorldRunScriptFunc) PushReturn(r0 error) { + f.PushHook(func(string, ...string) error { + return r0 + }) +} + +func (f *FakeWorldRunScriptFunc) nextHook() func(string, ...string) error { + f.mutex.Lock() + defer f.mutex.Unlock() + + if len(f.hooks) == 0 { + if f.defaultHook == nil { + panic("unexpected invocation of FakeWorld.RunScript") + } + return f.defaultHook + } + + hook := f.hooks[0] + f.hooks = f.hooks[1:] + return hook +} + +func (f *FakeWorldRunScriptFunc) appendCall(r0 FakeWorldRunScriptFuncCall) { + f.mutex.Lock() + f.history = append(f.history, r0) + f.mutex.Unlock() +} + +// History returns a sequence of FakeWorldRunScriptFuncCall objects +// describing the invocations of this function. +func (f *FakeWorldRunScriptFunc) History() []FakeWorldRunScriptFuncCall { + f.mutex.Lock() + history := make([]FakeWorldRunScriptFuncCall, len(f.history)) + copy(history, f.history) + f.mutex.Unlock() + + return history +} + +// FakeWorldRunScriptFuncCall is an object that describes an invocation +// of method RunScript on an instance of FakeWorld. +type FakeWorldRunScriptFuncCall struct { + // Name is the value of the 1st argument + // passed to this method invocation. + Name string + // ArgArgs is a slice containing the values of the variadic arguments + // passed to this method invocation. + ArgArgs []string + // Err is the value of the 1st result + // returned from this method invocation. + Err error +} + +// Args returns an interface slice containing the arguments of this invocation. +// The variadic slice argument is flattened in this array such that +// one positional argument and three variadic arguments +// would result in a slice of four, not two. +func (c FakeWorldRunScriptFuncCall) Args() []any { + trailing := []any{} + for _, val := range c.ArgArgs { + trailing = append(trailing, val) + } + + return append([]any{c.Name}, trailing...) +} + +// Results returns an interface slice containing the results of this invocation. +func (c FakeWorldRunScriptFuncCall) Results() []any { + return []any{c.Err} +} diff --git a/scripts/lint-docs/internal/mock.port_test.go b/scripts/lint-docs/internal/mock.port_test.go new file mode 100644 index 0000000..bd21b8b --- /dev/null +++ b/scripts/lint-docs/internal/mock.port_test.go @@ -0,0 +1,54 @@ +// Code generated by MockGen. DO NOT EDIT. +// Source: port.go +// +// Generated by this command: +// +// mockgen -source=port.go -destination=mock.port_test.go -package=internal_test -exclude_interfaces=World +// + +// Package internal_test is a generated GoMock package. +package internal_test + +import ( + reflect "reflect" + + gomock "go.uber.org/mock/gomock" +) + +// MockApp is a mock of App interface. +type MockApp struct { + ctrl *gomock.Controller + recorder *MockAppMockRecorder + isgomock struct{} +} + +// MockAppMockRecorder is the mock recorder for MockApp. +type MockAppMockRecorder struct { + mock *MockApp +} + +// NewMockApp creates a new mock instance. +func NewMockApp(ctrl *gomock.Controller) *MockApp { + mock := &MockApp{ctrl: ctrl} + mock.recorder = &MockAppMockRecorder{mock} + return mock +} + +// EXPECT returns an object that allows the caller to indicate expected use. +func (m *MockApp) EXPECT() *MockAppMockRecorder { + return m.recorder +} + +// Check mocks base method. +func (m *MockApp) Check() error { + m.ctrl.T.Helper() + ret := m.ctrl.Call(m, "Check") + ret0, _ := ret[0].(error) + return ret0 +} + +// Check indicates an expected call of Check. +func (mr *MockAppMockRecorder) Check() *gomock.Call { + mr.mock.ctrl.T.Helper() + return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Check", reflect.TypeOf((*MockApp)(nil).Check)) +} diff --git a/scripts/lint-docs/internal/port.go b/scripts/lint-docs/internal/port.go new file mode 100644 index 0000000..f7540e9 --- /dev/null +++ b/scripts/lint-docs/internal/port.go @@ -0,0 +1,25 @@ +//go:generate mockgen -source=port.go -destination=mock.port_test.go -package=internal_test -exclude_interfaces=World + +// Package internal implements task lint:docs. +package internal + +import "errors" + +// Errors. +var ( + ErrNoScriptsBin = errors.New("SCRIPTS_BIN is empty") +) + +// App is the application. +type App interface { + // Check runs checks of markdown files. + // It runs all checks, even after a failed one. + Check() error +} + +// World abstracts commands for testability. +type World interface { + // RunScript runs a binary of a Go script and waits for its exit. + // Output of the binary goes to stdout and stderr of the program. + RunScript(name string, args ...string) error +} diff --git a/scripts/lint-docs/internal/wire.go b/scripts/lint-docs/internal/wire.go new file mode 100644 index 0000000..058960a --- /dev/null +++ b/scripts/lint-docs/internal/wire.go @@ -0,0 +1,14 @@ +package internal + +import "os" + +// WireApp wires the application with real commands. +// +//nolint:iface // Intentionally returning a port interface for wire.go. +func WireApp() App { + return NewApp(RealWorld{ + ScriptsBin: os.Getenv("SCRIPTS_BIN"), + Stdout: os.Stdout, + Stderr: os.Stderr, + }) +} diff --git a/scripts/lint-docs/internal/world.go b/scripts/lint-docs/internal/world.go new file mode 100644 index 0000000..64c1ade --- /dev/null +++ b/scripts/lint-docs/internal/world.go @@ -0,0 +1,26 @@ +package internal + +import ( + "io" + "path/filepath" + + "github.com/bitfield/script" +) + +// RealWorld implements [World] by real commands. +type RealWorld struct { + ScriptsBin string // Directory of binaries of Go scripts. + Stdout io.Writer + Stderr io.Writer +} + +// RunScript implements [World]. +func (w RealWorld) RunScript(name string, args ...string) error { + if w.ScriptsBin == "" { // A bare name would be looked up in PATH. + return ErrNoScriptsBin + } + _, err := script.NewPipe().WithStdout(w.Stdout).WithStderr(w.Stderr). + ExecCommand(filepath.Join(w.ScriptsBin, name), args...). + Stdout() + return err +} diff --git a/scripts/lint-docs/internal/world_test.go b/scripts/lint-docs/internal/world_test.go new file mode 100644 index 0000000..097115c --- /dev/null +++ b/scripts/lint-docs/internal/world_test.go @@ -0,0 +1,63 @@ +package internal_test + +import ( + "bytes" + "fmt" + "os" + "path/filepath" + "strconv" + "strings" + "testing" + + "github.com/powerman/check" + + "github.com/powerman/go-scripts-example/scripts/lint-docs/internal" +) + +// fakeScriptEnv makes the test binary act as a binary of a Go script, +// which exits with the status given by this variable. +const fakeScriptEnv = "LINT_DOCS_FAKE_SCRIPT_EXIT" + +func TestMain(m *testing.M) { + if status, ok := os.LookupEnv(fakeScriptEnv); ok { + os.Exit(fakeScript(status)) + } + m.Run() +} + +// fakeScript prints arguments to stdout, one per line, and a message to stderr. +// It returns the exit status. +func fakeScript(status string) int { + code, err := strconv.Atoi(status) + if err != nil { + panic(err) + } + fmt.Fprintln(os.Stdout, strings.Join(os.Args[1:], "\n")) + fmt.Fprintln(os.Stderr, "fake script") + return code +} + +// TestRealWorld_RunScript checks arguments, output and exit status of a binary +// by running the test binary as a binary of a Go script. +// Its name has no .exe, like a name of a script on Windows. +// +//nolint:paralleltest // The fake script gets its exit status by an environment variable. +func TestRealWorld_RunScript(tt *testing.T) { + t := check.T(tt).MustAll() + exe, err := os.Executable() + t.Nil(err) + name := strings.TrimSuffix(filepath.Base(exe), ".exe") + var stdout, stderr bytes.Buffer + w := internal.RealWorld{ScriptsBin: filepath.Dir(exe), Stdout: &stdout, Stderr: &stderr} + + t.Setenv(fakeScriptEnv, "0") + t.Nil(w.RunScript(name, "a b", "")) + t.Equal(stdout.String(), "a b\n\n") + t.Equal(stderr.String(), "fake script\n") + + t.Setenv(fakeScriptEnv, "3") + t.Match(w.RunScript(name), `exit status 3`) + + w.ScriptsBin = "" + t.Err(w.RunScript(name), internal.ErrNoScriptsBin) +} diff --git a/scripts/lint-docs/main.go b/scripts/lint-docs/main.go new file mode 100644 index 0000000..da9e1d0 --- /dev/null +++ b/scripts/lint-docs/main.go @@ -0,0 +1,21 @@ +// Lint-docs checks markdown files by other scripts. +// It is an example of a mise task in Go which runs binaries of other Go scripts. +package main + +import ( + "github.com/alecthomas/kong" + + "github.com/powerman/go-scripts-example/scripts/lint-docs/internal" +) + +func main() { + var cli internal.CLI + ctx := kong.Parse(&cli, + kong.Name("lint:docs"), + kong.Description("Check that tables of contents in markdown files are up to date"+ + " and their local links aren't broken."), + kong.UsageOnError(), + ) + ctx.BindTo(internal.WireApp(), (*internal.App)(nil)) + ctx.FatalIfErrorf(ctx.Run()) +} diff --git a/scripts/lint-links/internal/cmd_test.go b/scripts/lint-links/internal/cmd_test.go index 4f75d5f..f9aa063 100644 --- a/scripts/lint-links/internal/cmd_test.go +++ b/scripts/lint-links/internal/cmd_test.go @@ -20,7 +20,7 @@ func kongRun(t *check.C, a internal.App, args ...string) error { t.Helper() var cli internal.CLI k, err := kong.New(&cli, - kong.Name("lint:links"), + kong.Name("lint-links"), kong.Writers(io.Discard, io.Discard), kong.Exit(func(int) {}), ) @@ -59,5 +59,5 @@ func TestCLI_Run(tt *testing.T) { func TestUsageSpec(t *testing.T) { t.Parallel() - kongusage.CheckSpec(t, kong.Must(&internal.CLI{}, kong.Name("lint:links"))) + kongusage.CheckSpec(t, kong.Must(&internal.CLI{}, kong.Name("lint-links"))) } diff --git a/scripts/lint-links/internal/port.go b/scripts/lint-links/internal/port.go index 4e86014..a49d8fb 100644 --- a/scripts/lint-links/internal/port.go +++ b/scripts/lint-links/internal/port.go @@ -1,6 +1,6 @@ //go:generate mockgen -source=port.go -destination=mock.port_test.go -package=internal_test -exclude_interfaces=World -// Package internal implements task lint:links. +// Package internal implements program lint-links. package internal import "errors" diff --git a/scripts/lint-links/main.go b/scripts/lint-links/main.go index 0ae8908..dffc753 100644 --- a/scripts/lint-links/main.go +++ b/scripts/lint-links/main.go @@ -1,5 +1,5 @@ // Lint-links checks local links in markdown files. -// It is an example of a mise task in Go. +// It is an example of a Go script without a mise task, run by another Go script. package main import ( @@ -11,7 +11,7 @@ import ( func main() { var cli internal.CLI ctx := kong.Parse(&cli, - kong.Name("lint:links"), + kong.Name("lint-links"), kong.Description("Check that local links in markdown files point to files of the repository"+ " and to existing headings of markdown files."), kong.UsageOnError(), diff --git a/scripts/tasks.toml b/scripts/tasks.toml index e08111d..e4e9c9f 100644 --- a/scripts/tasks.toml +++ b/scripts/tasks.toml @@ -9,27 +9,28 @@ go mod tidy ''' ['scripts:build'] -description = 'Build Go scripts into .cache/bin/' +description = 'Build Go scripts into $SCRIPTS_BIN' hide = true depends = 'scripts:build:clean' dir = 'scripts' silent = 'stdout' # Hide "sources up-to-date, skipping", but keep build errors. sources = ['**/*'] -outputs = ['../.cache/bin/*'] -run = 'go build -o ../.cache/bin/ ./...' +outputs = ['{{env.SCRIPTS_BIN}}/*'] +run = 'go build -o "${SCRIPTS_BIN:?}/" ./...' +run_windows = 'go build -o "%SCRIPTS_BIN%/" ./...' ['scripts:build:clean'] -description = 'Remove programs of removed Go scripts from .cache/bin/' +description = 'Remove binaries of removed Go scripts from $SCRIPTS_BIN' hide = true quiet = true run = ''' -for f in .cache/bin/*; do - [ -d "scripts/${f#.cache/bin/}" ] || rm -f "$f" +for f in "${SCRIPTS_BIN:?}"/*; do + [ -d "scripts/${f##*/}" ] || rm -f "$f" done ''' run_windows = """ -powershell -NoProfile -Command "if (Test-Path .cache/bin) { \ - Get-ChildItem .cache/bin -File \ +powershell -NoProfile -Command "if (Test-Path $env:SCRIPTS_BIN) { \ + Get-ChildItem $env:SCRIPTS_BIN -File \ | Where-Object { -not (Test-Path -PathType Container scripts/$($_.BaseName)) } \ | Remove-Item }"\ """ @@ -73,7 +74,7 @@ description = 'Lint usage specs of Go scripts' hide = true depends = 'scripts:build' run = ''' -for f in .cache/bin/*; do +for f in "${SCRIPTS_BIN:?}"/*; do spec=$("$f" --usage-spec) printf '%s\n' "$spec" | usage lint -W - done diff --git a/scripts/test-qemu/internal/app.go b/scripts/test-qemu/internal/app.go index 05ededb..2dc7075 100644 --- a/scripts/test-qemu/internal/app.go +++ b/scripts/test-qemu/internal/app.go @@ -22,15 +22,14 @@ const ( var reVolume = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9_.-]*$`) // containerScript runs in the alpine image, which has no git needed by scripts. -// The repository is mounted read-only, so programs are built outside of it. -// Programs run in the container to check that they work on its platform. +// The repository is mounted read-only, so binaries are built outside of it. +// Binaries run in the container to check that they work on its platform. const containerScript = ` apk add --no-cache git >/dev/null git config --global --add safe.directory ` + workdir + ` go -C scripts test -timeout=60s ./... -go -C scripts build -o /tmp/bin/ ./... -/tmp/bin/toc --check -/tmp/bin/lint-links +go -C scripts build -o "$SCRIPTS_BIN/" ./... +"$SCRIPTS_BIN/lint-docs" ` // hintQEMU is printed with architectures of platforms whose containers can't run. @@ -84,7 +83,10 @@ func (a *app) Test(opts Options) error { goCache, goModCache, }, - Env: []string{"KONGUSAGE_TEST_SKIP_USAGE=1"}, // Tool usage isn't in the image. + Env: []string{ + "SCRIPTS_BIN=/tmp/bin", + "KONGUSAGE_TEST_SKIP_USAGE=1", // Tool usage isn't in the image. + }, Cmd: []string{"sh", "-e", "-c", containerScript}, } // A failure of tests and a failure to start a container of a platform are told apart diff --git a/scripts/test-qemu/internal/app_test.go b/scripts/test-qemu/internal/app_test.go index 1a056b3..62f2c26 100644 --- a/scripts/test-qemu/internal/app_test.go +++ b/scripts/test-qemu/internal/app_test.go @@ -95,7 +95,7 @@ func container(platform, image string, cmd []string) internal.Container { {Source: "gocache", Target: "/root/.cache/go-build"}, {Source: "gomodcache", Target: "/go/pkg/mod"}, }, - Env: []string{"KONGUSAGE_TEST_SKIP_USAGE=1"}, + Env: []string{"SCRIPTS_BIN=/tmp/bin", "KONGUSAGE_TEST_SKIP_USAGE=1"}, Cmd: cmd, } }