Skip to main content

check-definite-antecedents.yml

Diff-scoped heuristic that flags a div whose first sentence opens with a definite phrase and no link, and a demonstrative (this, that, these, those) standing alone as a pronoun (gha#1460). The bare-demonstrative finding is detected by what follows the word (a verb, preposition, conjunction, sentence end, or a predicate adjective after “make”); <!-- check-definite-antecedents: allow --> on a line exempts it. A line gets at most one demonstrative finding. A whole-tree run (whole-tree: true) on an existing corpus reports many hits, so add allow comments or fix them before adopting it that way. Both findings fail by default. The lab’s rule (Ezra, 2026-10-19) is that a definite noun phrase needs a clear antecedent, linked to where it is introduced unless that is in the same div or passage. This implements the check for psw#291.

A grammar-aware check is out of reach, so the check covers the clearest case. The first sentence of a div’s body (or of a file with no div) starts with “The”, “These”, “Those”, “This” or “That”, and holds no Markdown link, no @ cross-reference and no include shortcode. Nothing earlier in that div can be the antecedent, so the reader has none unless a link supplies one. The finding sits on that line.

A third finding, pronoun, flags a div whose first sentence starts with “It”, “Its”, “They”, “Them”, or “Their” (gha#1955, for psw#608). A link elsewhere in that sentence does not exempt it, since the pronoun still refers to something the div has not named. A pronoun later in the sentence is not checked, because most such pronouns have an antecedent earlier in the same sentence. It fails by default, like the other two.

The check does not count:

A definition that starts “The covariance function must be …” is reported although it may be fine, which is why the check never fails by default.

Scope

Only a first sentence on a line a pull request adds is reported. An added line whose exact text was also deleted in the same diff counts as moved rather than new, and a blank added line is not content. 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 in full on purpose. Every run prints how many lines, files and divs it examined.

Inputs

Input Type Default Description
globs string '*.qmd' 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 true Fail the workflow on a finding. Set false for warning annotations only.
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

See examples/check-definite-antecedents.yml for the caller stub.