From 9d150e7bbf3a640e796e87525fbda72d0e996b3a Mon Sep 17 00:00:00 2001 From: Aaron <7063649+ahcodedev@users.noreply.github.com> Date: Sat, 7 Nov 2026 09:18:54 -0800 Subject: [PATCH 1/2] Add prek, actionlint, gitleaks, and zizmor --- .github/dependabot.yml | 17 ++++++++ .github/pull_request_template.md | 9 +++++ .github/workflows/dependabot-auto-merge.yml | 30 ++++++++++++++ .github/workflows/template.yml | 39 +++++++++++++++++-- Brewfile | 10 +++++ README.md | 26 +++++++++++++ justfile | 9 +++++ prek.toml | 10 +++++ template/.devcontainer/devcontainer.json | 6 ++- template/.github/dependabot.yml | 26 +++++++++++++ template/.github/pull_request_template.md | 11 ++++++ .../workflows/dependabot-auto-merge.yml | 30 ++++++++++++++ template/.github/workflows/rust.yml | 36 +++++++++++++++-- template/Brewfile | 10 +++++ template/CLAUDE.md | 18 +++++++-- template/README.md.jinja | 30 ++++++++++++-- template/justfile | 11 +++++- template/prek.toml | 10 +++++ 18 files changed, 321 insertions(+), 17 deletions(-) create mode 100644 .github/dependabot.yml create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/dependabot-auto-merge.yml create mode 100644 prek.toml create mode 100644 template/.github/dependabot.yml create mode 100644 template/.github/pull_request_template.md create mode 100644 template/.github/workflows/dependabot-auto-merge.yml create mode 100644 template/prek.toml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..dc19837 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,17 @@ +# Dependabot version updates; patch and minor updates are auto-merged by dependabot-auto-merge.yml +version: 2 +updates: + # Actions in this repo's workflows and in the workflows rendered into new projects + - package-ecosystem: github-actions + directories: + - / + - /template + schedule: + interval: weekly + # Wait a week after a release, so broken or malicious versions are more likely to be caught first + cooldown: + default-days: 7 + groups: + github-actions: + patterns: + - "*" diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..074064e --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,9 @@ +## Summary + + + +## Checklist + +- [ ] `just lint` passes +- [ ] `just test-template` passes +- [ ] Docs updated if needed (`README.md`, `template/README.md.jinja`, `template/CLAUDE.md`) diff --git a/.github/workflows/dependabot-auto-merge.yml b/.github/workflows/dependabot-auto-merge.yml new file mode 100644 index 0000000..e601653 --- /dev/null +++ b/.github/workflows/dependabot-auto-merge.yml @@ -0,0 +1,30 @@ +name: Dependabot auto-merge + +# pull_request (not pull_request_target) is enough: Dependabot PRs come from a branch in this +# repository, so the token gets the permissions granted below +on: pull_request + +permissions: {} + +jobs: + auto-merge: + runs-on: ubuntu-latest + # Check the PR author rather than github.actor, which can be someone re-running the workflow + if: github.event.pull_request.user.login == 'dependabot[bot]' + permissions: + contents: write + pull-requests: write + + steps: + - name: Fetch Dependabot metadata + id: metadata + uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0 + + # Patch and minor updates merge once the required checks pass; major updates wait for review. + # Auto-merge must be allowed in the repository settings, with required status checks on main. + - name: Enable auto-merge for patch and minor updates + if: steps.metadata.outputs.update-type == 'version-update:semver-patch' || steps.metadata.outputs.update-type == 'version-update:semver-minor' + run: gh pr merge --auto --squash "$PR_URL" + env: + PR_URL: ${{ github.event.pull_request.html_url }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/template.yml b/.github/workflows/template.yml index 62ed463..3a22f94 100644 --- a/.github/workflows/template.yml +++ b/.github/workflows/template.yml @@ -23,7 +23,9 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + persist-credentials: false # Installs the toolchain and components pinned in the template's rust-toolchain.toml - name: Install Rust @@ -31,12 +33,43 @@ jobs: run: rustup toolchain install - name: Install just - uses: taiki-e/install-action@v2 + uses: taiki-e/install-action@3a3daafd3b7f23b8f65d9f5ba2db203fb59b79e2 # v2 with: - tool: just + tool: just,zizmor,uv + + # actionlint isn't available from install-action; install it from PyPI with uv + - name: Install actionlint + run: | + uv tool install actionlint-py==1.7.12.25 + uv tool dir --bin >> "$GITHUB_PATH" + + - name: Lint workflows + run: just lint - name: Install Copier run: pipx install copier - name: Generate and test project run: just test-template + + gitleaks: + runs-on: ubuntu-latest + # Job-level permissions replace the workflow-level ones, so contents: read is repeated here. + # pull-requests: read lets the action list a PR's commits, which private repos require. + permissions: + contents: read + pull-requests: read + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + # Full history so every commit is scanned for secrets + fetch-depth: 0 + persist-credentials: false + + - name: Scan for secrets + uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3.0.0 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # PR comments would need the pull-requests: write permission + GITLEAKS_ENABLE_COMMENTS: false diff --git a/Brewfile b/Brewfile index 628849b..338a230 100644 --- a/Brewfile +++ b/Brewfile @@ -3,3 +3,13 @@ # Project template tool (see copier.yml) brew "copier" brew "just" + +# GitHub Actions linters +brew "actionlint" +brew "zizmor" + +# Git hook manager (see prek.toml); run `prek install` once to enable hooks +brew "prek" + +# Secret scanner (prek hook and `just gitleaks`) +brew "gitleaks" diff --git a/README.md b/README.md index 96101f2..9a68469 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,33 @@ Rust project template for [Copier](https://copier.readthedocs.io/). - Create a new project - `copier copy gh:/rust-template path/to/new-project` - Pull in template updates from inside a generated project - `copier update` +## Development + +- Install Copier, `just`, actionlint, zizmor, prek and gitleaks - `brew bundle` +- Enable the Git hooks in `prek.toml` - `prek install` + - Before each commit they run `just lint` and scan the staged changes for secrets with gitleaks + +Commands are defined in the `justfile` and run with [just](https://github.com/casey/just). + +- List available commands - `just` +- Check GitHub Actions workflows with actionlint and zizmor - `just lint` +- Render the template into a temp directory, then lint and test the generated project - `just test-template` +- Scan the Git history for committed secrets - `just gitleaks` + +CI runs `just lint` and `just test-template`, and scans the Git history for secrets with gitleaks. + +## Dependency Updates + +- Dependabot (`.github/dependabot.yml`) opens weekly PRs for GitHub Actions in this repo's workflows and in `template/` + - Updates wait 7 days after a release before a PR is opened +- Patch and minor updates are auto-merged once CI passes (`.github/workflows/dependabot-auto-merge.yml`); major updates wait for review + - Auto-merge needs "Allow auto-merge" turned on in the repository settings and a branch protection rule or ruleset on `main` that requires the CI checks + - On GitHub Free, branch protection and auto-merge are only available for public repos +- Dependabot doesn't update the actionlint version in the workflows and dev container, the gitleaks version and image in the dev container, or anything in `.jinja` files + ## Layout - `copier.yml` - template questions and settings - `template/` - files rendered into new projects; files ending in `.jinja` are templated +- `prek.toml` - Git hooks for this repo +- `.github/pull_request_template.md` - checklist filled into new PR descriptions diff --git a/justfile b/justfile index 1cc96d1..31afb1f 100644 --- a/justfile +++ b/justfile @@ -3,6 +3,11 @@ default: @just --list +# Check GitHub Actions workflows with actionlint and audit them for security issues with zizmor +lint: + actionlint .github/workflows/*.yml + zizmor . + # Render the template into a temp directory, then lint and test the generated project test-template: #!/usr/bin/env bash @@ -18,3 +23,7 @@ test-template: cd "$tmp/test-project" just lint just test + +# Scan the Git history for committed secrets (pass extra flags, e.g. `just gitleaks --log-opts=-5`) +gitleaks *args: + gitleaks git --redact {{args}} diff --git a/prek.toml b/prek.toml new file mode 100644 index 0000000..c376572 --- /dev/null +++ b/prek.toml @@ -0,0 +1,10 @@ +# Git hooks managed by prek (https://prek.j178.dev). Install with: prek install + +[[repos]] +repo = "local" +hooks = [ + # Run the same checks as CI before each commit + { id = "just-lint", name = "just lint", entry = "just lint", language = "system", pass_filenames = false, always_run = true }, + # Block commits that add secrets (scans only the staged changes) + { id = "gitleaks", name = "gitleaks", entry = "gitleaks git --pre-commit --staged --redact", language = "system", pass_filenames = false, always_run = true }, +] diff --git a/template/.devcontainer/devcontainer.json b/template/.devcontainer/devcontainer.json index 0da99aa..87db15d 100644 --- a/template/.devcontainer/devcontainer.json +++ b/template/.devcontainer/devcontainer.json @@ -8,8 +8,10 @@ "capAdd": ["SYS_PTRACE"], "securityOpt": ["seccomp=unconfined"], - // Install the toolchain pinned in rust-toolchain.toml and the `just` command runner - "postCreateCommand": "rustup toolchain install && sudo apt-get update && sudo apt-get install -y --no-install-recommends just", + // Install the toolchain pinned in rust-toolchain.toml, the `just` command runner, the zizmor workflow linter, + // uv and actionlint (from PyPI, since Debian doesn't package it), the prek Git hook manager and the gitleaks secret scanner (a checksum-verified GitHub + // release, since Debian's package is too old), then install the hooks if the workspace is a Git repository + "postCreateCommand": "rustup toolchain install && sudo apt-get update && sudo apt-get install -y --no-install-recommends just && cargo install --locked zizmor prek uv && uv tool install actionlint-py==1.7.12.25 && uv tool update-shell && v=8.30.1 && a=$(dpkg --print-architecture | sed s/amd64/x64/) && cd /tmp && curl -fsSLO https://github.com/gitleaks/gitleaks/releases/download/v$v/gitleaks_${v}_linux_$a.tar.gz && curl -fsSL https://github.com/gitleaks/gitleaks/releases/download/v$v/gitleaks_${v}_checksums.txt | sha256sum --check --ignore-missing && sudo tar -xzf gitleaks_${v}_linux_$a.tar.gz -C /usr/local/bin gitleaks && rm gitleaks_${v}_linux_$a.tar.gz && cd - && if [ -e .git ]; then prek install; fi", "customizations": { "vscode": { diff --git a/template/.github/dependabot.yml b/template/.github/dependabot.yml new file mode 100644 index 0000000..3f24153 --- /dev/null +++ b/template/.github/dependabot.yml @@ -0,0 +1,26 @@ +# Dependabot version updates; patch and minor updates are auto-merged by dependabot-auto-merge.yml +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly + # Wait a week after a release, so broken or malicious versions are more likely to be caught first + cooldown: + default-days: 7 + groups: + github-actions: + patterns: + - "*" + + - package-ecosystem: cargo + directory: / + schedule: + interval: weekly + # Wait a week after a release, so broken or malicious versions are more likely to be caught first + cooldown: + default-days: 7 + groups: + cargo: + patterns: + - "*" diff --git a/template/.github/pull_request_template.md b/template/.github/pull_request_template.md new file mode 100644 index 0000000..0c3988c --- /dev/null +++ b/template/.github/pull_request_template.md @@ -0,0 +1,11 @@ +## Summary + + + +## Checklist + +- [ ] `just fmt` has been run +- [ ] `just lint` passes +- [ ] `just test` passes +- [ ] Tests added or updated for new behaviour +- [ ] Docs updated if needed (`README.md`, `CLAUDE.md`) diff --git a/template/.github/workflows/dependabot-auto-merge.yml b/template/.github/workflows/dependabot-auto-merge.yml new file mode 100644 index 0000000..e601653 --- /dev/null +++ b/template/.github/workflows/dependabot-auto-merge.yml @@ -0,0 +1,30 @@ +name: Dependabot auto-merge + +# pull_request (not pull_request_target) is enough: Dependabot PRs come from a branch in this +# repository, so the token gets the permissions granted below +on: pull_request + +permissions: {} + +jobs: + auto-merge: + runs-on: ubuntu-latest + # Check the PR author rather than github.actor, which can be someone re-running the workflow + if: github.event.pull_request.user.login == 'dependabot[bot]' + permissions: + contents: write + pull-requests: write + + steps: + - name: Fetch Dependabot metadata + id: metadata + uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0 + + # Patch and minor updates merge once the required checks pass; major updates wait for review. + # Auto-merge must be allowed in the repository settings, with required status checks on main. + - name: Enable auto-merge for patch and minor updates + if: steps.metadata.outputs.update-type == 'version-update:semver-patch' || steps.metadata.outputs.update-type == 'version-update:semver-minor' + run: gh pr merge --auto --squash "$PR_URL" + env: + PR_URL: ${{ github.event.pull_request.html_url }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/template/.github/workflows/rust.yml b/template/.github/workflows/rust.yml index 46b7b22..28c900b 100644 --- a/template/.github/workflows/rust.yml +++ b/template/.github/workflows/rust.yml @@ -23,7 +23,9 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + persist-credentials: false # Installs the toolchain and components pinned in rust-toolchain.toml - name: Install Rust @@ -33,12 +35,40 @@ jobs: # uses: Swatinem/rust-cache@v2 - name: Install just - uses: taiki-e/install-action@v2 + uses: taiki-e/install-action@3a3daafd3b7f23b8f65d9f5ba2db203fb59b79e2 # v2 with: - tool: just + tool: just,zizmor,uv + + # actionlint isn't available from install-action; install it from PyPI with uv + - name: Install actionlint + run: | + uv tool install actionlint-py==1.7.12.25 + uv tool dir --bin >> "$GITHUB_PATH" - name: Lint run: just lint - name: Test run: just test + + gitleaks: + runs-on: ubuntu-latest + # Job-level permissions replace the workflow-level ones, so contents: read is repeated here. + # pull-requests: read lets the action list a PR's commits, which private repos require. + permissions: + contents: read + pull-requests: read + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + # Full history so every commit is scanned for secrets + fetch-depth: 0 + persist-credentials: false + + - name: Scan for secrets + uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3.0.0 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # PR comments would need the pull-requests: write permission + GITLEAKS_ENABLE_COMMENTS: false diff --git a/template/Brewfile b/template/Brewfile index 378b003..7742f88 100644 --- a/template/Brewfile +++ b/template/Brewfile @@ -10,6 +10,16 @@ brew "just" # Project template tool; run `copier update` to pull in template changes brew "copier" +# GitHub Actions linters (run by `just lint`) +brew "actionlint" +brew "zizmor" + +# Git hook manager (see prek.toml); `just setup` installs the hooks +brew "prek" + +# Secret scanner (prek hook and `just gitleaks`) +brew "gitleaks" + # Dev tools # brew "bacon" # background checker: re-runs clippy/tests on save # brew "cargo-nextest" # faster test runner diff --git a/template/CLAUDE.md b/template/CLAUDE.md index fb98913..b0544e4 100644 --- a/template/CLAUDE.md +++ b/template/CLAUDE.md @@ -6,19 +6,31 @@ Guidance for Claude Code when working in this repository. Run project tasks through `just` (see `justfile`) rather than calling `cargo` directly. On macOS, Homebrew's `rustup` is keg-only, so `cargo` may not be on the shell PATH; the `justfile` adds it for every recipe. -- `just setup` - install Homebrew dependencies and the pinned toolchain +- `just setup` - install Homebrew dependencies, the pinned toolchain and the prek Git hooks (`prek.toml`), which run `just lint` before each commit - `just build` - build (pass extra flags, e.g. `just build --release`) - `just test` - run tests (pass a filter, e.g. `just test greeting`) - `just fmt` - format all code -- `just lint` - check formatting and run clippy with warnings as errors +- `just lint` - check formatting, run clippy with warnings as errors, and check GitHub Actions workflows with actionlint and zizmor +- `just gitleaks` - scan the Git history for committed secrets -Run `just fmt` and `just lint` after making changes; CI runs `just lint` and `just test` and fails on any warning. +Run `just fmt` and `just lint` after making changes; CI runs `just lint` and `just test` and fails on any warning, and scans the Git history for secrets with gitleaks. + +## Git hooks + +prek (`prek.toml`) runs `just lint` and a gitleaks scan of the staged changes before each commit. + +- Don't bypass the hooks with `--no-verify`; fix the reported problem instead +- If gitleaks flags a secret, remove it from the change rather than adding an allowlist entry, unless asked ## Layout - `src/lib.rs` - library crate; put application logic here so it can be tested - `src/main.rs` - thin binary entry point that calls into the library - `tests/` - integration tests against the library's public API +- `.github/workflows/rust.yml` - CI; actions are pinned to commit hashes with a version comment, keep that style +- `.github/workflows/dependabot-auto-merge.yml` - auto-merges Dependabot patch and minor updates once CI passes +- `.github/dependabot.yml` - weekly Dependabot updates for Cargo and GitHub Actions, with a 7-day cooldown +- `.github/pull_request_template.md` - PR description checklist; follow it when writing PR descriptions ## Toolchain diff --git a/template/README.md.jinja b/template/README.md.jinja index 386097a..cedb334 100644 --- a/template/README.md.jinja +++ b/template/README.md.jinja @@ -7,7 +7,8 @@ ### macOS - Install `just` - `brew install just` -- Install Homebrew dependencies and the Rust toolchain pinned in `rust-toolchain.toml` - `just setup` +- Install Homebrew dependencies, the Rust toolchain pinned in `rust-toolchain.toml` and the Git hooks - `just setup` + - Run `git init` first; the hooks are only installed in a Git repository - Verify the setup - `just test` Homebrew's `rustup` is keg-only, so `cargo` and `rustc` aren't on your shell PATH. The `justfile` adds them for every recipe, so use `just` commands rather than calling `cargo` directly. To use `cargo` in your shell, add this to `~/.zshrc`: @@ -19,20 +20,41 @@ export PATH="$(brew --prefix rustup)/bin:$PATH" ### Dev Container - Open the repo in VS Code and run **Dev Containers: Reopen in Container** - - Rust, `just`, and the recommended extensions are installed automatically + - Rust, `just`, actionlint, zizmor, prek, gitleaks and the recommended extensions are installed automatically + - The Git hooks are installed if the workspace is a Git repository ## Project Commands Commands are defined in the `justfile` and run with [just](https://github.com/casey/just). - List available commands - `just` -- Install Homebrew dependencies and the pinned toolchain - `just setup` +- Install Homebrew dependencies, the pinned toolchain and the Git hooks - `just setup` - Build the project - `just build` - Pass extra flags - `just build --release` - Run tests - `just test` - Pass extra args - `just test greeting` - Format all code - `just fmt` -- Check formatting and run clippy with warnings as errors - `just lint` +- Check formatting, run clippy with warnings as errors, and check GitHub Actions workflows with actionlint and zizmor - `just lint` +- Scan the Git history for committed secrets - `just gitleaks` + +## Checks + +- Git hooks, managed by [prek](https://github.com/j178/prek) (`prek.toml`), run before each commit + - `just lint` + - [gitleaks](https://github.com/gitleaks/gitleaks) on the staged changes + - Install them manually with `prek install` +- CI runs `just lint` and `just test`, and scans the Git history for secrets with gitleaks + - Repos owned by a GitHub organization need a `GITLEAKS_LICENSE` secret for the gitleaks job; personal repos don't + - Dependabot PRs only get Dependabot secrets, so organization repos also need `GITLEAKS_LICENSE` added as a Dependabot secret + +## Dependency Updates + +- Dependabot (`.github/dependabot.yml`) opens weekly PRs for Cargo dependencies and GitHub Actions + - Updates wait 7 days after a release before a PR is opened +- Patch and minor updates are auto-merged once CI passes (`.github/workflows/dependabot-auto-merge.yml`); major updates wait for review + - Auto-merge needs "Allow auto-merge" turned on in the repository settings and a branch protection rule or ruleset on `main` that requires the CI checks + - On GitHub Free, branch protection and auto-merge are only available for public repos +- Dependabot doesn't update the actionlint version in the workflows and dev container, or the gitleaks version and image in the dev container ## Template diff --git a/template/justfile b/template/justfile index b0bd9b0..d048cb7 100644 --- a/template/justfile +++ b/template/justfile @@ -8,12 +8,13 @@ default: rustup_prefix := `brew --prefix rustup 2>/dev/null || true` export PATH := if rustup_prefix != "" { rustup_prefix / "bin" + ":" + env("PATH") } else { env("PATH") } -# Install Homebrew dependencies and the pinned toolchain +# Install Homebrew dependencies, the pinned toolchain and the prek Git hooks setup: brew bundle install rustup toolchain install rustc --version cargo --version + prek install # Build the project (pass extra flags, e.g. `just build --release`) build *args: @@ -27,7 +28,13 @@ test *args: fmt: cargo fmt --all -# Check formatting and run clippy with warnings as errors +# Check formatting, run clippy with warnings as errors, and check GitHub Actions workflows lint: cargo fmt --all --check cargo clippy --all-targets --all-features -- -D warnings + actionlint .github/workflows/*.yml + zizmor . + +# Scan the Git history for committed secrets (pass extra flags, e.g. `just gitleaks --log-opts=-5`) +gitleaks *args: + gitleaks git --redact {{args}} diff --git a/template/prek.toml b/template/prek.toml new file mode 100644 index 0000000..c376572 --- /dev/null +++ b/template/prek.toml @@ -0,0 +1,10 @@ +# Git hooks managed by prek (https://prek.j178.dev). Install with: prek install + +[[repos]] +repo = "local" +hooks = [ + # Run the same checks as CI before each commit + { id = "just-lint", name = "just lint", entry = "just lint", language = "system", pass_filenames = false, always_run = true }, + # Block commits that add secrets (scans only the staged changes) + { id = "gitleaks", name = "gitleaks", entry = "gitleaks git --pre-commit --staged --redact", language = "system", pass_filenames = false, always_run = true }, +] From 0cc383fb8d572190c459d9ca19500465dfedc4ee Mon Sep 17 00:00:00 2001 From: Aaron <7063649+ahcodedev@users.noreply.github.com> Date: Sat, 7 Nov 2026 11:22:18 -0800 Subject: [PATCH 2/2] Add cargo tools, linters, and project checks; Update copier config --- .github/workflows/template.yml | 2 +- Brewfile | 7 +++ README.md | 10 +++- copier.yml | 14 +++-- justfile | 56 +++++++++++++++++- template/.devcontainer/devcontainer.json | 7 ++- template/.github/workflows/rust.yml | 26 +++++++- template/Brewfile | 9 ++- template/CLAUDE.md | 24 +++++--- template/Cargo.toml.jinja | 11 +++- template/LICENSE.jinja | 2 +- template/README.md.jinja | 37 ++++++++---- template/bacon.toml | 10 ++++ template/deny.toml | 34 +++++++++++ template/justfile | 75 +++++++++++++++++++++--- template/rust-toolchain.toml | 3 +- template/src/lib.rs | 4 ++ template/src/main.rs.jinja | 2 + template/tests/greeting.rs.jinja | 2 + 19 files changed, 289 insertions(+), 46 deletions(-) create mode 100644 template/bacon.toml create mode 100644 template/deny.toml diff --git a/.github/workflows/template.yml b/.github/workflows/template.yml index 3a22f94..c1fa1ac 100644 --- a/.github/workflows/template.yml +++ b/.github/workflows/template.yml @@ -35,7 +35,7 @@ jobs: - name: Install just uses: taiki-e/install-action@3a3daafd3b7f23b8f65d9f5ba2db203fb59b79e2 # v2 with: - tool: just,zizmor,uv + tool: just,zizmor,uv,cargo-deny,cargo-nextest,cargo-shear,cargo-llvm-cov,typos,tombi # actionlint isn't available from install-action; install it from PyPI with uv - name: Install actionlint diff --git a/Brewfile b/Brewfile index 338a230..1598bc5 100644 --- a/Brewfile +++ b/Brewfile @@ -4,6 +4,13 @@ brew "copier" brew "just" +# Rust toolchain manager; `just setup` uses it to install cargo-binstall and the Rust tools +# (see `cargo_tools` in the justfile), and `just test-template` builds the generated project +brew "rustup" + +# TOML formatter (run by `just lint`) +brew "tombi" + # GitHub Actions linters brew "actionlint" brew "zizmor" diff --git a/README.md b/README.md index 9a68469..79559b4 100644 --- a/README.md +++ b/README.md @@ -9,15 +9,19 @@ Rust project template for [Copier](https://copier.readthedocs.io/). ## Development -- Install Copier, `just`, actionlint, zizmor, prek and gitleaks - `brew bundle` +- Install `just` - `brew install just` +- Install Copier, rustup, tombi, actionlint, zizmor, prek and gitleaks with Homebrew, then cargo-binstall and the pinned Rust tools (cargo-deny, cargo-nextest, cargo-shear, cargo-llvm-cov, typos) with cargo - `just setup` + - Change tool versions in `cargo_tools` at the top of the `justfile`; reinstall with `just install-tools` + - Bump them all to the latest releases and install them - `just update` - Enable the Git hooks in `prek.toml` - `prek install` - Before each commit they run `just lint` and scan the staged changes for secrets with gitleaks Commands are defined in the `justfile` and run with [just](https://github.com/casey/just). - List available commands - `just` -- Check GitHub Actions workflows with actionlint and zizmor - `just lint` -- Render the template into a temp directory, then lint and test the generated project - `just test-template` +- Format TOML files with tombi - `just fmt` +- Check spelling with typos, TOML formatting with tombi, and GitHub Actions workflows with actionlint and zizmor - `just lint` +- Render the template into a temp directory, then lint, test, check coverage and check dependencies of the generated project - `just test-template` - Scan the Git history for committed secrets - `just gitleaks` CI runs `just lint` and `just test-template`, and scans the Git history for secrets with gitleaks. diff --git a/copier.yml b/copier.yml index a1820e1..fed15ce 100644 --- a/copier.yml +++ b/copier.yml @@ -1,6 +1,14 @@ -_min_copier_version: "9.0.0" +_min_copier_version: "9.6.0" _subdirectory: template +# Starter code is only created by `copier copy`. `copier update` skips these files, so a project +# can change, move or delete them without an update recreating or overwriting them. +# (`_copier_operation` needs Copier 9.6.0 or later.) +_exclude: + - "{% if _copier_operation == 'update' %}src/lib.rs{% endif %}" + - "{% if _copier_operation == 'update' %}src/main.rs{% endif %}" + - "{% if _copier_operation == 'update' %}tests/greeting.rs{% endif %}" + project_name: type: str help: Cargo package name (lowercase letters, digits, hyphens and underscores) @@ -19,10 +27,6 @@ description: help: Short description of the project default: "" -author_name: - type: str - help: Name used in the LICENSE copyright line - copyright_year: type: str help: Year used in the LICENSE copyright line diff --git a/justfile b/justfile index 31afb1f..75cef9a 100644 --- a/justfile +++ b/justfile @@ -3,12 +3,62 @@ default: @just --list -# Check GitHub Actions workflows with actionlint and audit them for security issues with zizmor +# Homebrew's rustup is keg-only, so neither rustup nor its cargo/rustc proxies +# are on PATH. Prepend its bin directory for all recipes when Homebrew is available, +# plus Cargo's bin directory, where `just install-tools` puts the Rust tools. +rustup_prefix := `brew --prefix rustup 2>/dev/null || true` +cargo_bin := env("CARGO_HOME", home_directory() / ".cargo") / "bin" +export PATH := cargo_bin + ":" + if rustup_prefix != "" { rustup_prefix / "bin" + ":" + env("PATH") } else { env("PATH") } + +# Rust tools installed by `just install-tools` as prebuilt binaries with cargo-binstall; bump versions here +binstall_version := "1.26.2" +cargo_tools := "cargo-deny@0.20.2 cargo-nextest@0.9.151 cargo-shear@1.14.0 cargo-llvm-cov@0.9.1 typos-cli@1.52.0" + +# Install Homebrew dependencies and the Rust tools that `just lint` and `just test-template` need +setup: + brew bundle install + just install-tools + +# Install the pinned Rust tools (`cargo_tools`), installing cargo-binstall from source first if it's missing +install-tools: + command -v cargo-binstall >/dev/null || cargo install --locked cargo-binstall@{{binstall_version}} + cargo binstall --no-confirm {{cargo_tools}} + +# Bump `binstall_version` and the `cargo_tools` versions in this justfile to their latest releases, then install them +update: + #!/usr/bin/env bash + set -euo pipefail + latest() { + local version + version="$(cargo info --registry crates-io "$1" 2>/dev/null | sed -n 's/^version: \([^ ]*\).*/\1/p' | head -1)" + [[ -n "$version" ]] || { echo "could not find the latest version of $1" >&2; exit 1; } + echo "$version" + } + binstall="$(latest cargo-binstall)" + tools="" + for tool in {{cargo_tools}}; do + name="${tool%@*}" + tools+="${tools:+ }$name@$(latest "$name")" + done + # perl rather than sed -i, which takes different arguments on macOS and Linux; the versions are + # passed through the environment so perl doesn't treat the `@` in `name@version` as an array + BINSTALL="$binstall" TOOLS="$tools" perl -pi -e 's/^binstall_version := ".*"/binstall_version := "$ENV{BINSTALL}"/; s/^cargo_tools := ".*"/cargo_tools := "$ENV{TOOLS}"/' "{{justfile()}}" + echo "binstall_version := \"$binstall\"" + echo "cargo_tools := \"$tools\"" + just install-tools + +# Format TOML files +fmt: + tombi format + +# Check spelling with typos and TOML formatting with tombi, check GitHub Actions workflows with actionlint and audit them for security issues with zizmor lint: + typos + tombi format --check actionlint .github/workflows/*.yml zizmor . -# Render the template into a temp directory, then lint and test the generated project +# Render the template into a temp directory, then lint, test, check coverage and check dependencies of the generated project test-template: #!/usr/bin/env bash set -euo pipefail @@ -23,6 +73,8 @@ test-template: cd "$tmp/test-project" just lint just test + just coverage + just deny # Scan the Git history for committed secrets (pass extra flags, e.g. `just gitleaks --log-opts=-5`) gitleaks *args: diff --git a/template/.devcontainer/devcontainer.json b/template/.devcontainer/devcontainer.json index 87db15d..87b83de 100644 --- a/template/.devcontainer/devcontainer.json +++ b/template/.devcontainer/devcontainer.json @@ -8,10 +8,11 @@ "capAdd": ["SYS_PTRACE"], "securityOpt": ["seccomp=unconfined"], - // Install the toolchain pinned in rust-toolchain.toml, the `just` command runner, the zizmor workflow linter, - // uv and actionlint (from PyPI, since Debian doesn't package it), the prek Git hook manager and the gitleaks secret scanner (a checksum-verified GitHub + // Install the toolchain pinned in rust-toolchain.toml, the `just` command runner, the zizmor workflow linter, the Rust tools in the justfile's + // `cargo_tools` (cargo-deny, cargo-nextest, cargo-shear, cargo-llvm-cov, typos) with cargo-binstall via `just install-tools`, + // uv, actionlint and the tombi TOML formatter (from PyPI, since Debian doesn't package them), the prek Git hook manager and the gitleaks secret scanner (a checksum-verified GitHub // release, since Debian's package is too old), then install the hooks if the workspace is a Git repository - "postCreateCommand": "rustup toolchain install && sudo apt-get update && sudo apt-get install -y --no-install-recommends just && cargo install --locked zizmor prek uv && uv tool install actionlint-py==1.7.12.25 && uv tool update-shell && v=8.30.1 && a=$(dpkg --print-architecture | sed s/amd64/x64/) && cd /tmp && curl -fsSLO https://github.com/gitleaks/gitleaks/releases/download/v$v/gitleaks_${v}_linux_$a.tar.gz && curl -fsSL https://github.com/gitleaks/gitleaks/releases/download/v$v/gitleaks_${v}_checksums.txt | sha256sum --check --ignore-missing && sudo tar -xzf gitleaks_${v}_linux_$a.tar.gz -C /usr/local/bin gitleaks && rm gitleaks_${v}_linux_$a.tar.gz && cd - && if [ -e .git ]; then prek install; fi", + "postCreateCommand": "rustup toolchain install && sudo apt-get update && sudo apt-get install -y --no-install-recommends just && cargo install --locked zizmor prek uv && just install-tools && uv tool install actionlint-py==1.7.12.25 && uv tool install tombi && uv tool update-shell && v=8.30.1 && a=$(dpkg --print-architecture | sed s/amd64/x64/) && cd /tmp && curl -fsSLO https://github.com/gitleaks/gitleaks/releases/download/v$v/gitleaks_${v}_linux_$a.tar.gz && curl -fsSL https://github.com/gitleaks/gitleaks/releases/download/v$v/gitleaks_${v}_checksums.txt | sha256sum --check --ignore-missing && sudo tar -xzf gitleaks_${v}_linux_$a.tar.gz -C /usr/local/bin gitleaks && rm gitleaks_${v}_linux_$a.tar.gz && cd - && if [ -e .git ]; then prek install; fi", "customizations": { "vscode": { diff --git a/template/.github/workflows/rust.yml b/template/.github/workflows/rust.yml index 28c900b..0bceba6 100644 --- a/template/.github/workflows/rust.yml +++ b/template/.github/workflows/rust.yml @@ -37,7 +37,7 @@ jobs: - name: Install just uses: taiki-e/install-action@3a3daafd3b7f23b8f65d9f5ba2db203fb59b79e2 # v2 with: - tool: just,zizmor,uv + tool: just,zizmor,uv,cargo-deny,cargo-nextest,cargo-shear,cargo-llvm-cov,typos,tombi # actionlint isn't available from install-action; install it from PyPI with uv - name: Install actionlint @@ -51,6 +51,30 @@ jobs: - name: Test run: just test + - name: Coverage + run: just coverage + + # Separate from Lint: a newly published advisory can fail this step without any code change + - name: Check dependencies + run: just deny + + msrv: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + persist-credentials: false + + - name: Install just + uses: taiki-e/install-action@3a3daafd3b7f23b8f65d9f5ba2db203fb59b79e2 # v2 + with: + tool: just + + # Installs the toolchain set by rust-version in Cargo.toml and checks the project builds with it + - name: Check minimum supported Rust version + run: just msrv + gitleaks: runs-on: ubuntu-latest # Job-level permissions replace the workflow-level ones, so contents: read is repeated here. diff --git a/template/Brewfile b/template/Brewfile index 7742f88..cdf3d88 100644 --- a/template/Brewfile +++ b/template/Brewfile @@ -10,6 +10,9 @@ brew "just" # Project template tool; run `copier update` to pull in template changes brew "copier" +# TOML formatter (run by `just lint`) +brew "tombi" + # GitHub Actions linters (run by `just lint`) brew "actionlint" brew "zizmor" @@ -20,6 +23,8 @@ brew "prek" # Secret scanner (prek hook and `just gitleaks`) brew "gitleaks" +# cargo-deny, cargo-nextest, cargo-shear, cargo-llvm-cov and typos are installed by `just setup` +# with cargo-binstall (see `cargo_tools` in the justfile) + # Dev tools -# brew "bacon" # background checker: re-runs clippy/tests on save -# brew "cargo-nextest" # faster test runner +# brew "bacon" # re-runs tests on save (see bacon.toml) diff --git a/template/CLAUDE.md b/template/CLAUDE.md index b0544e4..1d1d3bc 100644 --- a/template/CLAUDE.md +++ b/template/CLAUDE.md @@ -4,16 +4,21 @@ Guidance for Claude Code when working in this repository. ## Commands -Run project tasks through `just` (see `justfile`) rather than calling `cargo` directly. On macOS, Homebrew's `rustup` is keg-only, so `cargo` may not be on the shell PATH; the `justfile` adds it for every recipe. +Run project tasks through `just` (see `justfile`) rather than calling `cargo` directly. On macOS, Homebrew's `rustup` is keg-only, so `cargo` may not be on the shell PATH, and neither may the tools in `~/.cargo/bin`; the `justfile` adds both for every recipe. -- `just setup` - install Homebrew dependencies, the pinned toolchain and the prek Git hooks (`prek.toml`), which run `just lint` before each commit +- `just setup` - install Homebrew dependencies, the pinned toolchain, the Rust tools (via `just install-tools`) and the prek Git hooks (`prek.toml`), which run `just lint` before each commit +- `just install-tools` - install the Rust tools pinned in `cargo_tools` at the top of the `justfile` with cargo-binstall; bump versions there +- `just update` - bump `binstall_version` and `cargo_tools` in the `justfile` to the latest releases, then install them - `just build` - build (pass extra flags, e.g. `just build --release`) -- `just test` - run tests (pass a filter, e.g. `just test greeting`) -- `just fmt` - format all code -- `just lint` - check formatting, run clippy with warnings as errors, and check GitHub Actions workflows with actionlint and zizmor +- `just test` - run tests with cargo-nextest, then doc tests with `cargo test --doc` (pass a filter, e.g. `just test greeting`) +- `just coverage` - run tests with coverage; fails below `coverage_threshold`% line coverage (set at the top of the `justfile`; `src/main.rs` excluded) +- `just fmt` - format all Rust and TOML code (rustfmt and tombi) +- `just lint` - check spelling with typos and Rust and TOML formatting, run clippy and rustdoc with warnings as errors (catches broken doc links), check for unused dependencies with cargo-shear, and check GitHub Actions workflows with actionlint and zizmor +- `just msrv` - check the project builds with its minimum supported Rust version (`rust-version` in `Cargo.toml`) +- `just deny` - check dependencies for security advisories, licenses, banned crates and sources (`deny.toml`) - `just gitleaks` - scan the Git history for committed secrets -Run `just fmt` and `just lint` after making changes; CI runs `just lint` and `just test` and fails on any warning, and scans the Git history for secrets with gitleaks. +Run `just fmt` and `just lint` after making changes; CI runs `just lint`, `just test`, `just coverage`, `just deny` and `just msrv` and fails on any warning, and scans the Git history for secrets with gitleaks. ## Git hooks @@ -26,7 +31,9 @@ prek (`prek.toml`) runs `just lint` and a gitleaks scan of the staged changes be - `src/lib.rs` - library crate; put application logic here so it can be tested - `src/main.rs` - thin binary entry point that calls into the library -- `tests/` - integration tests against the library's public API +- `tests/` - integration tests against the library's public API; add tests for new code so `just coverage` stays above the threshold, and don't lower `coverage_threshold` unless asked +- `bacon.toml` - optional bacon config; re-runs nextest on save +- `deny.toml` - cargo-deny rules; when adding a dependency with a new license, ask before adding it to `allow` - `.github/workflows/rust.yml` - CI; actions are pinned to commit hashes with a version comment, keep that style - `.github/workflows/dependabot-auto-merge.yml` - auto-merges Dependabot patch and minor updates once CI passes - `.github/dependabot.yml` - weekly Dependabot updates for Cargo and GitHub Actions, with a 7-day cooldown @@ -35,7 +42,8 @@ prek (`prek.toml`) runs `just lint` and a gitleaks scan of the staged changes be ## Toolchain - The Rust version is pinned in `rust-toolchain.toml`; don't change it unless asked -- Edition 2024; minimum supported Rust version is set by `rust-version` in `Cargo.toml` +- Edition 2024; minimum supported Rust version is set by `rust-version` in `Cargo.toml` and checked by `just msrv`; don't use features newer than it +- Lint levels are set in the `[lints]` table in `Cargo.toml`: `unsafe_code` is forbidden, public items and every crate root (including `main.rs` and each file in `tests/`) need doc comments, and clippy's pedantic lints are on. Fix lint warnings rather than adding `#[allow]` or changing `[lints]`, unless asked ## Template diff --git a/template/Cargo.toml.jinja b/template/Cargo.toml.jinja index 6b16710..49a064d 100644 --- a/template/Cargo.toml.jinja +++ b/template/Cargo.toml.jinja @@ -2,10 +2,19 @@ name = "{{ project_name }}" version = "0.1.0" edition = "2024" -rust-version = "1.85" +rust-version = "1.99" {%- if description %} description = "{{ description }}" {%- endif %} license = "MIT" [dependencies] + +# Lint levels for rustc, clippy and rustdoc. CI runs clippy with -D warnings, so "warn" fails CI. +[lints.clippy] +# priority = -1 lets individual clippy lints listed here override the group +pedantic = { level = "warn", priority = -1 } + +[lints.rust] +missing_docs = "warn" +unsafe_code = "forbid" diff --git a/template/LICENSE.jinja b/template/LICENSE.jinja index 360dcee..2a3945c 100644 --- a/template/LICENSE.jinja +++ b/template/LICENSE.jinja @@ -1,6 +1,6 @@ MIT License -Copyright (c) {{ copyright_year }} {{ author_name }} +Copyright (c) {{ copyright_year }} Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/template/README.md.jinja b/template/README.md.jinja index cedb334..9505879 100644 --- a/template/README.md.jinja +++ b/template/README.md.jinja @@ -7,20 +7,22 @@ ### macOS - Install `just` - `brew install just` -- Install Homebrew dependencies, the Rust toolchain pinned in `rust-toolchain.toml` and the Git hooks - `just setup` - - Run `git init` first; the hooks are only installed in a Git repository +- Install Homebrew dependencies, the Rust toolchain pinned in `rust-toolchain.toml`, the Rust tools and the Git hooks - `just setup` + - The Rust tools (cargo-deny, cargo-nextest, cargo-shear, cargo-llvm-cov, typos) are installed as prebuilt binaries with [cargo-binstall](https://github.com/cargo-bins/cargo-binstall), which is installed with `cargo install` first if needed + - Their versions are pinned in `cargo_tools` at the top of the `justfile`; reinstall with `just install-tools` + - `just setup` is built to run in an established Git repository (it fails otherwise); run `git init` first if needed - Verify the setup - `just test` -Homebrew's `rustup` is keg-only, so `cargo` and `rustc` aren't on your shell PATH. The `justfile` adds them for every recipe, so use `just` commands rather than calling `cargo` directly. To use `cargo` in your shell, add this to `~/.zshrc`: +Homebrew's `rustup` is keg-only, so `cargo` and `rustc` aren't on your shell PATH, and neither are the tools in `~/.cargo/bin`. The `justfile` adds both for every recipe, so use `just` commands rather than calling `cargo` directly. To use them in your shell, add this to `~/.zshrc`: ```sh -export PATH="$(brew --prefix rustup)/bin:$PATH" +export PATH="$HOME/.cargo/bin:$(brew --prefix rustup)/bin:$PATH" ``` ### Dev Container - Open the repo in VS Code and run **Dev Containers: Reopen in Container** - - Rust, `just`, actionlint, zizmor, prek, gitleaks and the recommended extensions are installed automatically + - Rust, `just`, cargo-deny, cargo-nextest, cargo-shear, cargo-llvm-cov, typos, tombi, actionlint, zizmor, prek, gitleaks and the recommended extensions are installed automatically - The Git hooks are installed if the workspace is a Git repository ## Project Commands @@ -28,22 +30,37 @@ export PATH="$(brew --prefix rustup)/bin:$PATH" Commands are defined in the `justfile` and run with [just](https://github.com/casey/just). - List available commands - `just` -- Install Homebrew dependencies, the pinned toolchain and the Git hooks - `just setup` +- Install Homebrew dependencies, the pinned toolchain, the Rust tools and the Git hooks - `just setup` +- Install or update the pinned Rust tools (`cargo_tools` in the `justfile`) - `just install-tools` +- Bump the pinned Rust tools to their latest releases in the `justfile`, then install them - `just update` - Build the project - `just build` - Pass extra flags - `just build --release` -- Run tests - `just test` +- Run tests with [nextest](https://nexte.st), then doc tests - `just test` - Pass extra args - `just test greeting` -- Format all code - `just fmt` -- Check formatting, run clippy with warnings as errors, and check GitHub Actions workflows with actionlint and zizmor - `just lint` +- Run tests with coverage; fails below 98% line coverage - `just coverage` + - Change the minimum in `coverage_threshold` at the top of the `justfile`, or once with `just coverage_threshold=90 coverage` + - `src/main.rs` is excluded, and doc tests aren't counted +- Format all Rust and TOML code (rustfmt and tombi) - `just fmt` +- Check spelling with typos and Rust and TOML formatting, run clippy and rustdoc with warnings as errors, check for unused dependencies with cargo-shear, and check GitHub Actions workflows with actionlint and zizmor - `just lint` +- Check the project builds with its minimum supported Rust version (`rust-version` in `Cargo.toml`) - `just msrv` +- Check dependencies for security advisories, licenses, banned crates and sources (`deny.toml`) - `just deny` + - Run a single check - `just deny licenses` - Scan the Git history for committed secrets - `just gitleaks` +Optional: re-run the tests each time you save with [bacon](https://dystroy.org/bacon/) (`bacon.toml`). + +- Install - `brew install bacon` +- Run in a terminal - `bacon` + - Press `c` for clippy, `d` for docs or `t` to go back to tests +- bacon calls `cargo` directly, so on macOS add Homebrew's `rustup` to your PATH first (see Setup) + ## Checks - Git hooks, managed by [prek](https://github.com/j178/prek) (`prek.toml`), run before each commit - `just lint` - [gitleaks](https://github.com/gitleaks/gitleaks) on the staged changes - Install them manually with `prek install` -- CI runs `just lint` and `just test`, and scans the Git history for secrets with gitleaks +- CI runs `just lint`, `just test`, `just coverage`, `just deny` and `just msrv`, and scans the Git history for secrets with gitleaks - Repos owned by a GitHub organization need a `GITLEAKS_LICENSE` secret for the gitleaks job; personal repos don't - Dependabot PRs only get Dependabot secrets, so organization repos also need `GITLEAKS_LICENSE` added as a Dependabot secret diff --git a/template/bacon.toml b/template/bacon.toml new file mode 100644 index 0000000..feea2b3 --- /dev/null +++ b/template/bacon.toml @@ -0,0 +1,10 @@ +# bacon (https://dystroy.org/bacon/) re-runs a job each time you save. It's optional: install with +# `brew install bacon`, then run `bacon` in a terminal. bacon's built-in jobs (check, clippy, doc, ...) +# are still available, e.g. `bacon clippy-all`. + +# Re-run the tests with nextest, like `just test` +default_job = "nextest" + +[keybindings] +# Press `t` for nextest rather than bacon's default `cargo test` job +t = "job:nextest" diff --git a/template/deny.toml b/template/deny.toml new file mode 100644 index 0000000..2809147 --- /dev/null +++ b/template/deny.toml @@ -0,0 +1,34 @@ +# cargo-deny configuration (https://embarkstudios.github.io/cargo-deny/). Run with: just deny + +[graph] +all-features = true + +# Fail on crates with security advisories, or that are unmaintained or yanked +[advisories] +ignore = [] + +# Only allow common permissive licenses; add others here as dependencies need them +[licenses] +allow = [ + "Apache-2.0", + "Apache-2.0 WITH LLVM-exception", + "BSD-2-Clause", + "BSD-3-Clause", + "ISC", + "MIT", + "Unicode-3.0", + "Zlib", +] +# Don't warn about licenses in the list that no current dependency uses +unused-allowed-license = "allow" + +# Warn when several versions of the same crate are in the dependency tree +[bans] +multiple-versions = "warn" +wildcards = "deny" + +# Only allow crates from crates.io +[sources] +unknown-registry = "deny" +unknown-git = "deny" +allow-registry = ["https://github.com/rust-lang/crates.io-index"] diff --git a/template/justfile b/template/justfile index d048cb7..d61eb37 100644 --- a/template/justfile +++ b/template/justfile @@ -4,37 +4,98 @@ default: @just --list # Homebrew's rustup is keg-only, so neither rustup nor its cargo/rustc proxies -# are on PATH. Prepend its bin directory for all recipes when Homebrew is available. +# are on PATH. Prepend its bin directory for all recipes when Homebrew is available, +# plus Cargo's bin directory, where `just install-tools` puts the Rust tools. rustup_prefix := `brew --prefix rustup 2>/dev/null || true` -export PATH := if rustup_prefix != "" { rustup_prefix / "bin" + ":" + env("PATH") } else { env("PATH") } +cargo_bin := env("CARGO_HOME", home_directory() / ".cargo") / "bin" +export PATH := cargo_bin + ":" + if rustup_prefix != "" { rustup_prefix / "bin" + ":" + env("PATH") } else { env("PATH") } -# Install Homebrew dependencies, the pinned toolchain and the prek Git hooks +# Rust tools installed by `just install-tools` as prebuilt binaries with cargo-binstall; bump versions here +binstall_version := "1.26.2" +cargo_tools := "cargo-deny@0.20.2 cargo-nextest@0.9.151 cargo-shear@1.14.0 cargo-llvm-cov@0.9.1 typos-cli@1.52.0" + +# Minimum line coverage (%) for `just coverage`; override once with `just coverage_threshold=90 coverage` +coverage_threshold := "98" + +# Install Homebrew dependencies, the pinned toolchain, the Rust tools and the prek Git hooks setup: brew bundle install rustup toolchain install rustc --version cargo --version + just install-tools prek install +# Install the pinned Rust tools (`cargo_tools`), installing cargo-binstall from source first if it's missing +install-tools: + command -v cargo-binstall >/dev/null || cargo install --locked cargo-binstall@{{binstall_version}} + cargo binstall --no-confirm {{cargo_tools}} + +# Bump `binstall_version` and the `cargo_tools` versions in this justfile to their latest releases, then install them +update: + #!/usr/bin/env bash + set -euo pipefail + latest() { + local version + version="$(cargo info --registry crates-io "$1" 2>/dev/null | sed -n 's/^version: \([^ ]*\).*/\1/p' | head -1)" + [[ -n "$version" ]] || { echo "could not find the latest version of $1" >&2; exit 1; } + echo "$version" + } + binstall="$(latest cargo-binstall)" + tools="" + for tool in {{cargo_tools}}; do + name="${tool%@*}" + tools+="${tools:+ }$name@$(latest "$name")" + done + # perl rather than sed -i, which takes different arguments on macOS and Linux; the versions are + # passed through the environment so perl doesn't treat the `@` in `name@version` as an array + BINSTALL="$binstall" TOOLS="$tools" perl -pi -e 's/^binstall_version := ".*"/binstall_version := "$ENV{BINSTALL}"/; s/^cargo_tools := ".*"/cargo_tools := "$ENV{TOOLS}"/' "{{justfile()}}" + echo "binstall_version := \"$binstall\"" + echo "cargo_tools := \"$tools\"" + just install-tools + # Build the project (pass extra flags, e.g. `just build --release`) build *args: cargo build {{args}} -# Run tests (pass extra args, e.g. `just test greeting`) +# Run tests with nextest, then doc tests, which nextest doesn't run (pass extra args, e.g. `just test greeting`) test *args: - cargo test {{args}} + cargo nextest run {{args}} + cargo test --doc -# Format all code +# Run tests with coverage and fail below `coverage_threshold`% line coverage (src/main.rs is excluded; doc tests aren't counted) +coverage *args: + cargo llvm-cov nextest --fail-under-lines {{coverage_threshold}} --ignore-filename-regex 'src/main\.rs$' {{args}} + +# Format all Rust and TOML code fmt: cargo fmt --all + tombi format -# Check formatting, run clippy with warnings as errors, and check GitHub Actions workflows +# Check spelling and Rust and TOML formatting, run clippy and rustdoc with warnings as errors, check for unused dependencies, and check GitHub Actions workflows lint: + typos cargo fmt --all --check + tombi format --check cargo clippy --all-targets --all-features -- -D warnings + RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features + cargo shear --deny-warnings actionlint .github/workflows/*.yml zizmor . +# Check the project builds with its minimum supported Rust version (`rust-version` in Cargo.toml) +msrv: + #!/usr/bin/env bash + set -euo pipefail + version="$(sed -n 's/^rust-version = "\(.*\)"$/\1/p' Cargo.toml)" + [[ -n "$version" ]] || { echo "rust-version not found in Cargo.toml" >&2; exit 1; } + rustup toolchain install "$version" --profile minimal + cargo "+$version" check --all-targets --all-features + +# Check dependencies for security advisories, licenses, banned crates and sources (pass a check, e.g. `just deny licenses`) +deny *args: + cargo deny check {{args}} + # Scan the Git history for committed secrets (pass extra flags, e.g. `just gitleaks --log-opts=-5`) gitleaks *args: gitleaks git --redact {{args}} diff --git a/template/rust-toolchain.toml b/template/rust-toolchain.toml index 503457c..056751a 100644 --- a/template/rust-toolchain.toml +++ b/template/rust-toolchain.toml @@ -1,4 +1,3 @@ [toolchain] - channel = "1.99.1" -components = ["clippy", "rustfmt"] +components = ["clippy", "rustfmt", "llvm-tools-preview"] diff --git a/template/src/lib.rs b/template/src/lib.rs index 59f6fe3..bcc9744 100644 --- a/template/src/lib.rs +++ b/template/src/lib.rs @@ -1,3 +1,7 @@ +//! Library crate: application logic lives here so it can be tested. + +/// Returns the greeting printed by the binary. +#[must_use] pub fn greeting() -> String { String::from("Hello, world!") } diff --git a/template/src/main.rs.jinja b/template/src/main.rs.jinja index 0e6a302..cf5a4ca 100644 --- a/template/src/main.rs.jinja +++ b/template/src/main.rs.jinja @@ -1,3 +1,5 @@ +//! Binary entry point: a thin wrapper that calls into the library. + fn main() { println!("{}", {{ crate_name }}::greeting()); } diff --git a/template/tests/greeting.rs.jinja b/template/tests/greeting.rs.jinja index 5e76592..f55bbe4 100644 --- a/template/tests/greeting.rs.jinja +++ b/template/tests/greeting.rs.jinja @@ -1,3 +1,5 @@ +//! Integration tests for the greeting. + use {{ crate_name }}::greeting; #[test]