diff --git a/.github/workflows/lint-include.yml b/.github/workflows/lint-include.yml index 55ed377d..ab66161b 100644 --- a/.github/workflows/lint-include.yml +++ b/.github/workflows/lint-include.yml @@ -102,7 +102,7 @@ on: type: boolean default: false lint-ruff: - description: "Run ruff (Python linting and formatting) when the repository has Python files — uploads SARIF" + description: "Run ruff (Python lint and format) when the repo has Python files and pins ruff — uploads SARIF" required: false type: boolean default: false diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 69012017..6364c515 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -94,7 +94,7 @@ on: type: boolean default: true lint-ruff: - description: "Run ruff (Python linting and formatting) when the repository has Python files — uploads SARIF" + description: "Run ruff (Python lint and format) when the repo has Python files and pins ruff — uploads SARIF" required: false type: boolean default: true diff --git a/docs/architecture.md b/docs/architecture.md index ac5f0245..0c4caede 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -180,9 +180,15 @@ mise install and the linter, so the job costs seconds. Generated and vendored paths don't count: the excludes of the shared `dprint.json` (Spec Kit output, APM-deployed agent files, `node_modules`, `.venv*`). +A language linter also runs only when the repository pins its tool in its mise +config: pinning is the opt-in. Without the pin, the linter is skipped with a +warning that names the fix, and the step passes, so a `lint.yml` bump never +turns a repository's CI red before it has adopted the linter. Once the tool is +pinned, findings fail the linter like any other. + - **ruff** (`lint-ruff`, Python, after v4.5.0) runs `ruff check` and - `ruff format --diff` on the `*.py` and `*.pyi` files. Pin `ruff` in the - repository's mise config. ruff reads the repository's own `ruff.toml`, + `ruff format --diff` on the `*.py` and `*.pyi` files once `ruff` is pinned + in the repository's mise config. ruff reads the repository's own `ruff.toml`, `.ruff.toml` or `[tool.ruff]` in `pyproject.toml`; config-sync's [`ruff.toml` template](../config-sync/templates/ruff.toml) is a starting point. Findings are annotated on the PR, and with `upload-sarif` they also go diff --git a/scripts/lint/ruff.sh b/scripts/lint/ruff.sh index 7b8b8d23..30d6e0d6 100755 --- a/scripts/lint/ruff.sh +++ b/scripts/lint/ruff.sh @@ -3,19 +3,25 @@ # Lints the repository's Python files with ruff and checks their formatting. # A step of .github/workflows/lint.yml, run the same way in both lint modes. # ruff reads the repository's own config (ruff.toml, .ruff.toml or pyproject.toml). +# Pinning ruff in the repository's mise config is the opt-in: without the pin +# ruff is skipped with a warning, so repositories adopt it on their own +# schedule instead of failing on the first lint.yml bump (#567). # Env: UPLOAD_SARIF: also write the lint findings as SARIF for code scanning, # and sarif=true to GITHUB_OUTPUT. set -eo pipefail lint_dir="$(dirname "${BASH_SOURCE[0]}")" -bash "${lint_dir}/require-mise-tool.sh" ruff mapfile -d '' files < <(bash "${lint_dir}/language-files.sh" python) # Without file arguments ruff would check the whole directory. if [ "${#files[@]}" -eq 0 ]; then echo "::notice::No Python files found; skipping ruff" exit 0 fi +if ! mise which ruff >/dev/null 2>&1; then + echo "::warning title=ruff is not pinned::This repository has Python files, but ruff is skipped because it isn't pinned in the repository's mise config. To lint them, pin ruff in .mise.toml (Renovate-managed), e.g. 'mise use ruff@', and add a ruff config: ruff.toml (config-sync has a template) or [tool.ruff] in pyproject.toml. Set lint-ruff: false to silence this warning." + exit 0 +fi # --force-exclude keeps the config's excludes for the files passed explicitly, # and --no-fix overrides a `fix = true` in it: checks must not edit the files. diff --git a/tests/lint-scripts.sh b/tests/lint-scripts.sh index 56413a7a..a35439ba 100755 --- a/tests/lint-scripts.sh +++ b/tests/lint-scripts.sh @@ -120,7 +120,7 @@ expect_out "::error::'dprint' is not pinned in this repository's mise config." " [ -z "${log}" ] || fail "an unpinned tool must not run: ${log}" # Every linter that needs a pinned tool checks for it first. -for script in dprint yamlfmt yamllint shellcheck shfmt trivy ruff; do +for script in dprint yamlfmt yamllint shellcheck shfmt trivy; do run "${script}" FAKE_TOOLS="" expect_status 1 "${script} without its tool" expect_out "::error::'${script}' is not pinned" "${script} without its tool" @@ -228,6 +228,16 @@ expect_status 0 "a repository without Python files" [ "${outputs}" = found=false ] || fail "expected found=false; got: ${outputs}" expect_out "::notice::No python files found; skipping its linter" "a repository without Python files" +# A repository with Python files that doesn't pin ruff opts out: ruff is +# skipped with a warning that names the fix, and the step passes (#567). +run_in "${code}" ruff +expect_status 0 "ruff without its pin" +expect_out "::warning title=ruff is not pinned::" "ruff without its pin" +expect_out "pin ruff in .mise.toml" "ruff without its pin" +expect_out "ruff.toml" "ruff without its pin" +[ -z "${log}" ] || fail "ruff must not run without its pin: ${log}" +[ -z "${outputs}" ] || fail "ruff without its pin must not report a SARIF report: ${outputs}" + # ruff lints and format-checks only those files, and writes SARIF for code # scanning without letting it gate the step. export FAKE_TOOLS="${FAKE_TOOLS} ruff" @@ -247,6 +257,9 @@ run_in "${code}" ruff expect_status 0 "ruff without Python files" expect_out "::notice::No Python files found; skipping ruff" "ruff without Python files" [ -z "${log}" ] || fail "ruff must not run without Python files: ${log}" +run_in "${code}" ruff FAKE_TOOLS="" +expect_out "::notice::No Python files found; skipping ruff" "a repository without Python files must not warn about the pin" +grep -Fq '::warning' <<<"${out}" && fail "a repository without Python files must not warn about the ruff pin: ${out}" # The SARIF filter drops checkov's skipped checks (level none) and tolerates a # missing report. diff --git a/workflow-templates/lint.yml b/workflow-templates/lint.yml index 60a9fcc3..1c98f546 100644 --- a/workflow-templates/lint.yml +++ b/workflow-templates/lint.yml @@ -63,7 +63,8 @@ jobs: # lint-trivy: true # lint-zizmor: true # Optional: needs a lint.yml release after v4.5.0; runs only when the - # repository has Python files. Pin ruff in your mise config. + # repository has Python files and pins ruff in its mise config (without + # the pin, ruff is skipped with a warning). # lint-ruff: true # lint-config-drift: false # Optional: report inline scripts in run: steps. Needs a lint.yml release