Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/lint-include.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 8 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 7 additions & 1 deletion scripts/lint/ruff.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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@<version>', 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.
Expand Down
15 changes: 14 additions & 1 deletion tests/lint-scripts.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand All @@ -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.
Expand Down
3 changes: 2 additions & 1 deletion workflow-templates/lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading