check-gradient-lhs.yml

Diff-scoped, warn-by-default check for the lab’s gradient rule (psw#488, gha#1538): when a page states a gradient, it writes the symbol as the left-hand side of an equation, not “its gradient is …”.

Rule

A line a pull request adds is flagged when its prose has the word “gradient” followed by “is” or “equals” and then math, a colon, or the end of the line, and no gradient symbol (\grad, \gradf, \gradwrt, or \nabla) comes before the first = of the equation. The equation is the inline math on the line, or the display equation that follows it. “The gradient is zero at the minimum” passes, since no equation follows.

The check does not read a code fence or code span, an HTML comment, YAML front matter, or a line carrying, or following, . It is a heuristic, so it warns by default.

Scope

There is no sweep: a file the pull request does not change is never reported, and only lines the pull request adds are reported. With no base-ref, or when the diff cannot be computed, the check skips with a warning and never falls back to a whole-tree scan. Set whole-tree: true to scan every tracked file in full on purpose.

Inputs

Input	Type	Default	Description
`globs`	string	`'.qmd .md'`	Space-separated git pathspecs of tracked files to check (recursive by default).
`paths-ignore`	string	`''`	Comma- or newline-separated glob patterns (relative paths) to skip. Supports ``, `?` and recursive `*`.
`fail`	boolean	`false`	Fail the workflow when a stated gradient has no symbol on the left. Set `true` once sampled hits are all real.
`whole-tree`	boolean	`false`	Scan every tracked file in full instead of only a PR’s added lines.
`python-version`	string	`'3.x'`	Python version to set up.
`runs-on`	string	empty (`CI_RUNNER` variable, else `ubuntu-latest`)	Runner label for the job. Use a self-hosted label only for a private repository; never for a public one, whose pull requests can run arbitrary code on it (#1167).

Permissions

Only contents: read (the default), so no permissions: block is needed.

Example

# Copy to .github/workflows/check-gradient-lhs.yml in your repo.
name: Check gradient left-hand sides

on:
  push:
    branches:
      - main
  pull_request:
  workflow_dispatch:

jobs:
  check:
    uses: Morrison-Lab/gha/.github/workflows/check-gradient-lhs.yml@v3
    # with:
    #   globs: '*.qmd *.md'                     # pathspecs to check (recursive)
    #   paths-ignore: 'chapters/outtakes/**'    # skip known-noisy paths
    #   fail: true                              # block instead of warn (defaults to false)
    #   whole-tree: true                        # scan every line, not just a PR's additions
    #   runs-on: private-runner                # self-hosted runner label (private repositories only)

See examples/check-gradient-lhs.yml for the full caller stub.