check-unexplained-contrasts.yml

Diff-scoped, warn-only check that flags a contrast in a definition, remark or note that cites no source. A contrast the text keeps (“X, not Y”) must say who holds the other reading, with a source, so it is not a straw man. If nobody holds the other reading, the contrast is deleted. This implements gha#1302 and the psw rule “Do not rule out readings no reader would make”.

Whether anyone holds the other reading is a fact about the literature, so a script cannot decide it. The check only prompts the author.

The check reports one of these phrases in a #def-, #rem- or #note- div that holds no citation: “, not for/as/a/an/the”, “does not mean”, “do not mean”, “not to be confused with”, “is not a/an” and “rather than a/an”. The finding sits on the line that holds the phrase.

The check does not read:

a div that holds a citation ([@key), since the source is the explanation;
lines inside a code fence, display math ($$) or an HTML comment;
inline code;
a div whose id is not def-, rem- or note-;
a line carrying .

The phrase list is noisy by design, which is why fail defaults to false.

Scope

Only an added line is reported. The whole file is parsed, since the div opens far above the changed line. An added line whose exact text was also deleted in the same diff counts as moved. With no base-ref, or when the diff cannot be computed, the check skips with a warning instead of scanning the whole tree. Set whole-tree: true to scan every tracked file on purpose, which measures how many existing contrasts lack a source.

Usage

Copy examples/check-unexplained-contrasts.yml to .github/workflows/ in your repository.

Inputs

Input	Default	Meaning
`globs`	`*.qmd`	Space-separated git pathspecs of tracked files to check
`paths-ignore`	empty	Comma- or newline-separated glob patterns to skip
`fail`	`false`	Fail the workflow on a finding instead of warning
`whole-tree`	`false`	Scan every contrast, not only a pull request’s additions
`runs-on`	empty (`CI_RUNNER` variable, else `ubuntu-latest`)	Runner label; self-hosted only for a private repository
`python-version`	`3.x`	Python version to set up

Permissions

The job needs contents: read only.

Example

name: Check for unexplained contrasts

on:
  pull_request:

jobs:
  check:
    uses: Morrison-Lab/gha/.github/workflows/check-unexplained-contrasts.yml@v3
    with:
      paths-ignore: 'chapters/outtakes/**'