diff --git a/README.md b/README.md index 0ec87d8..05574c7 100644 --- a/README.md +++ b/README.md @@ -10,33 +10,41 @@ A justfile used by osapi-io projects. ## 📦 Usage -Shared recipes are consumed as -[just modules](https://just.systems/man/en/modules.html). Each module has a -shim file (`*.mod.just`) that sets the working directory and imports the actual -recipe file. Both are fetched from this repo. +Shared recipes are consumed with `import?`. Each module is a single recipe file +whose recipes and variables are prefixed with the module name, fetched from this +repo into `.just/remote/`. ```just -mod go '.just/remote/go.mod.just' -mod bats '.just/remote/bats.mod.just' +import? '.just/remote/go.just' +import? '.just/remote/md.just' # Fetch shared justfiles from osapi-justfiles fetch: mkdir -p .just/remote - curl -sSfL https://raw.githubusercontent.com/osapi-io/osapi-justfiles/refs/heads/main/go.mod.just -o .just/remote/go.mod.just - curl -sSfL https://raw.githubusercontent.com/osapi-io/osapi-justfiles/refs/heads/main/go.just -o .just/remote/go.just - curl -sSfL https://raw.githubusercontent.com/osapi-io/osapi-justfiles/refs/heads/main/bats.mod.just -o .just/remote/bats.mod.just - curl -sSfL https://raw.githubusercontent.com/osapi-io/osapi-justfiles/refs/heads/main/bats.just -o .just/remote/bats.just + curl -sSfL https://raw.githubusercontent.com/osapi-io/osapi-justfiles/refs/heads/main/go/go.just -o .just/remote/go.just + curl -sSfL https://raw.githubusercontent.com/osapi-io/osapi-justfiles/refs/heads/main/md/md.just -o .just/remote/md.just ``` Then run `just fetch` to download the shared recipes, and they become available -under their module namespace: +by their prefixed names: ```bash -$ just fetch # Download shared justfiles -$ just go::deps # Install all Go tool dependencies -$ just go::test # Run all Go checks -$ just go::fmt # Auto-format code -$ just bats::test # Run BATS integration tests +$ just fetch # Download shared justfiles +$ just go-deps # Install all Go tool dependencies +$ just go-test # Run all Go checks +$ just go-fmt # Auto-format code +$ just md-fmt-check # Check markdown formatting +``` + +A module ships defaults for anything that varies by repository. To use a +different value, set `allow-duplicate-variables` and assign it again: + +```just +set allow-duplicate-variables + +import? '.just/remote/go.just' + +go_coverage_target := "99.9" ``` Add `.just/` to `.gitignore`: @@ -49,27 +57,30 @@ Add `.just/` to `.gitignore`: Each recipe installs its own tool dependencies on first use via private `_*-deps` recipes. There is no need to run `deps` before using a recipe — tools are -pulled automatically. `go::deps` is a convenience that installs all tools +pulled automatically. `go-deps` is a convenience that installs all tools upfront. Projects define a top-level `deps` recipe that calls each module's `deps`: ```just # Install all dependencies -deps: go::deps bats::deps +deps: + just go-deps go get -tool github.com/golang/mock/mockgen ``` ### Documentation generation -`go::docs` and `go::docs-check` use +`go-docs` and `go-docs-check` use [gomarkdoc](https://github.com/princjef/gomarkdoc) to generate one markdown file per package into `JUST_DOCS_DIR`, skipping `mocks` and `main` packages. -`docs-check` is **not** included in `go::test` by default — add it to your +`go-docs-check` is **not** included in `go-test` by default — add it to your project's `test` recipe where needed: ```just -test: go::test go::docs-check bats::test +test: + just go-test + just go-docs-check ``` ## ✨ Available Recipes @@ -85,25 +96,6 @@ Modules are moving into their own directories, each documenting itself: Modules not yet moved are documented inline below. -### docker.just - -| Recipe | Description | -| ------- | ------------------------------------- | -| `build` | Build the Docker image | -| `push` | Push the Docker image to the registry | - -**Environment variables:** - -- `JUST_DOCKER_IMAGE` - image name (default: `osapi-justfiles`) -- `JUST_DOCKER_TAG` - image tag (default: `latest`) - -Consuming projects can copy `.just` files directly from the image instead of -using `curl`: - -```dockerfile -COPY --from=registry.gitlab.com/osapi-io/osapi-justfiles:latest /*.just .just/remote/ -``` - ### just.just | Recipe | Description | diff --git a/bats.just b/bats.just deleted file mode 100644 index 5701624..0000000 --- a/bats.just +++ /dev/null @@ -1,39 +0,0 @@ -# Copyright (c) 2026 John Dewey -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to -# deal in the Software without restriction, including without limitation the -# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -# sell copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# The above copyright notice and this permission notice shall be included in -# all copies or substantial portions of the Software. -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -# DEALINGS IN THE SOFTWARE. -# BATS integration test recipes for osapi-io projects. - -# Install BATS and shfmt dependencies -[group('setup')] -deps: - go get github.com/bats-core/bats-core@latest - bash $(go env GOMODCACHE)/$(go list -m github.com/bats-core/bats-core | tr ' ' @)/install.sh ./vendor/bats - go install mvdan.cc/sh/v3/cmd/shfmt@latest - -# Reformat .bats files with shfmt -[group('fmt')] -fmt: - find . -name '*.bats' -not -path './test/vendor/*' -exec shfmt -w {} + - -# Check .bats file formatting -[group('fmt')] -fmt-check: - find . -name '*.bats' -not -path './test/vendor/*' -exec shfmt -l -d {} + - -# Run BATS integration tests -[group('test')] -test: fmt-check - ./vendor/bats/bin/bats . diff --git a/bats.mod.just b/bats.mod.just deleted file mode 100644 index 729b433..0000000 --- a/bats.mod.just +++ /dev/null @@ -1,3 +0,0 @@ -set working-directory := '../../test' - -import? 'bats.just' diff --git a/docker.just b/docker.just deleted file mode 100644 index 4e40cf7..0000000 --- a/docker.just +++ /dev/null @@ -1,33 +0,0 @@ -# Copyright (c) 2026 John Dewey -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to -# deal in the Software without restriction, including without limitation the -# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -# sell copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# The above copyright notice and this permission notice shall be included in -# all copies or substantial portions of the Software. -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -# DEALINGS IN THE SOFTWARE. -# Docker recipes for osapi-io projects. - -image_name := env("JUST_DOCKER_IMAGE", `basename $(git rev-parse --show-toplevel)`) -image_tag := env("JUST_DOCKER_TAG", "latest") -dockerfile := env("JUST_DOCKERFILE", "Dockerfile.local") - -# --- Build --- - -# Build the Docker image -[group('build')] -build: - docker build -f {{ dockerfile }} -t {{ image_name }}:{{ image_tag }} . - -# Push the Docker image to the registry -[group('build')] -push: - docker push {{ image_name }}:{{ image_tag }} diff --git a/docker.mod.just b/docker.mod.just deleted file mode 100644 index dbc70ad..0000000 --- a/docker.mod.just +++ /dev/null @@ -1,3 +0,0 @@ -set working-directory := '../..' - -import? 'docker.just'