[checks] Implement Python checks and fix some violations by eisenwave · Pull Request #9146 · cplusplus/draft

eisenwave · 2026-06-17T18:17:38Z

I've mentioned the option to improve the checks in Croydon to @tkoeppe, and he seemed generally open to the idea.

In summary, this PR converts all the checks we have in check-source.sh (plus some additional once adopted from check-output.sh) and turns them into a Python script. The benefits are:

Much nicer formatting for errors. You get VSCode-friendly source locations that you can use to navigate directly to the line and column in an editor. You also get a citation of the source with the affected column span highlighted, so you're not left guessing where the error is located.
No more hieroglyphic sed and grep piping. The code is relatively simple Python. It still uses a bunch of regular expressions for a lot of checks; the greatest benefits are in the more complex checks.
Ability to write test cases for checks using EXPECTCHECKNEXTLINE.
Ability to enable and disable individual checks for source spans using NOCHECKBEGIN and other directives. This makes it possible for us to add much more aggressive checks that would have previously been infeasible because they generate too much noise in old TeX sources.
- A good example of that is in this PR, where I disable the check for \tcode{\exposid{...}} in a part of numerics.tex because there are too many violations.
- We could also use this to e.g. disallow use of \textit in "newer" TeX ranges for example without having to fix every single violation. We could also use it to catch many "bad words" or "bad phrases" that appear too often to be checked right now, but that we don't want perpetuated.
- We could also use this to enforce a little bit of auto-enforcement of semantic line breaks (such as requiring a new line after a sentence period) without needing to fix the countless existing violations.
With check suppression, it is possible to suppress checks that would have inevitably failed during motions. For example, if there is a dangling \ref to a section that is introduced by another paper, you can still get a green build by suppressing the \ref check (that is, at least for the check-source checks).

There are a few notable new checks that make things a lot easier in the future:

base-env-balancing checks for balancing of \begin and \end commands. It's quite easy to get it wrong, and when you do, it tends to blow up after minutes during the TeX build in bizarre and hard-to-debug ways.
base-unknown-command checks for use of TeX commands that have never appeared before in the code base. It's very unlikely that this is intentional in most PRs, and very likely that someone just wrote \tocde instead of \tcode or something else stupid. If we need a new TeX command, we can just add it to the list.

eisenwave · 2026-06-17T19:07:32Z

Some more neat examples:

eisenwave · 2026-06-17T19:43:55Z

Latest innovation:

Tsche · 2026-06-19T11:33:58Z

+      - name: setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+
+      - name: install pyright
+        run: npm install -g pyright


I'm not sure pyright is a good call. There are other alternatives that do not require pulling in node as dependency.

I just use it because it integrates nicely with VSCode out of the box. What would you recommend instead?

I (still) tend to go for mypy for my own projects, but if this gives you a better user experience I'm okay with it.

Tsche · 2026-06-19T12:12:19Z

+        message: str,
+    ) -> None:
+        """Report a failure at `self.file_path`."""
+        emit_check_failure(


emit_check_failure is only called from within classes deriving from Check. Can you fold it into fail and consistently use this one?

After the changes in 7af3d56, I wouldn't want to. The difference is that fail is just a convenience function that provides the file path automatically, and I would want there to be a global "emit failure" function at some level, in case we expand the sources of failures in the future.

emit_check_failure is basically the global console.error counterpart, and that has kind of a right to exist even if you always use it via a wrapper. That might change at some point.

ok. Have you considered a configured global logger for this instead? Python's logging package is very useful.

eisenwave · 2026-06-19T13:37:05Z

@Tsche thanks a lot for the review. It'll take some time to clean it all up.

eisenwave · 2026-07-17T15:00:50Z

All the pre-existing issues are taken care of in separate PRs. Now comes rebasing on the latest motions and addressing all the feedback on the Python script.

1. Nested if statements get flagged. These are replaced with "and". 2. Mutable default initializers for members are flagged. Initialization is moved to __init__.

Tsche

I took a brief look at this again. Please note that some of the comments apply to multiple locations - I did not repeat them.

Tsche · 2026-07-30T17:24:13Z


-\definition{implementation-defined strict total order over pointers}
-{defns.order.ptr}
+\definition{implementation-defined strict total order over pointers}{defns.order.ptr}


this looks like an unrelated change, does it have to be in this patch?

Tsche · 2026-07-30T17:26:27Z

+    "reportUnknownParameterType": false,
+    "reportUnusedImport": true,
+    "reportUnusedVariable": true,
+    "pythonVersion": "3.12"


Is there any particular reason why this requires Python 3.12 rather than the current version (3.14)?

Tsche · 2026-07-30T17:30:49Z

+from data import *
+
+# ===============================================================================
+# Terminal color support


Please get rid of these section headers

Tsche · 2026-07-30T18:56:41Z

+        # Active-set management — controls whether check_line is called.
+        active: set[str] = set(all_ids)
+        # Per-check next-line skips: check_id → set of line numbers.


Please get rid of the LLMy em dashes and other unicode symbols (such as →) in comments. This might cause rendering issues with some editors and environments, I don't see a need to use anything but the ASCII-compatible subset here (even though Python assumes UTF-8 anyway).

Tsche · 2026-07-30T19:01:26Z

+    # -- Text checks -------------------------------------------------------------------------------
+    # Such checks run on all files and identify problems like illegal characters,
+    # trailing whitespace, etc.
+    # ----------------------------------------------------------------------------------------------
+    NonAsciiCheck("text-non-ascii-char"),
+    BannedPatternCheck(
+        "text-trailing-ws",
+        re.compile(r"\s+$"),
+        "Line has trailing whitespace; remove the extra spaces.",
+    ),
+    TrailingEmptyLinesCheck("text-trailing-empty-lines"),


Could you push those groups of checks into some CheckGroup object and attach the comment/name to it as strings?

That way you can reuse this for the command line interface (or well, its help text) to group checks and print a short description/name for those groups.

Tsche · 2026-08-03T05:01:42Z

+        message: str,
+    ) -> None:
+        """Report a failure at `self.file_path`."""
+        emit_check_failure(


ok. Have you considered a configured global logger for this instead? Python's logging package is very useful.

Tsche · 2026-08-03T05:05:32Z

+        help="Specific .tex files or directories to check (default: all .tex files"
+        " under the project root).",
+    )
+    args = parser.parse_args()


Please add a command/argument that just prints all checks and exits. Alternatively you could put this into the help text, but I'd prefer to (at least additionally) have a command.

If you do the check grouping thing I suggested this would allow filtering checks by group etc.

Tsche · 2026-08-03T05:06:23Z

+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(


Could we make it configurable which checks are performed? This could be useful to debug a specific failure.

Tsche · 2026-08-03T05:08:21Z

+    exit_code = num_failures > 1
+    sys.exit(exit_code)


exit_code seems extraneous. Please fold this into the sys.exit invocation.

Tsche · 2026-08-03T05:10:12Z

+
+    for file_path in tex_files:
+        lines = read_file(file_path)
+        for idx in range(len(lines) - 1):


how about
for idx, line in enumerate(lines[:-1]):

eisenwave requested a review from jensmaurer June 17, 2026 18:28

eisenwave changed the title ~~Implement Python checks and fix some violations~~ [checks] Implement Python checks and fix some violations Jun 17, 2026

Tsche suggested changes Jun 19, 2026

View reviewed changes

jensmaurer requested changes Jun 19, 2026

View reviewed changes

Comment thread source/numerics.tex Outdated

Comment thread source/numerics.tex

This was referenced Jun 20, 2026

[over.built] Add commas after "e.g." #9154

Merged

[simd] Remove unnecessary \tcode around \exposid #9155

Merged

eisenwave force-pushed the python-checks branch from 9e27d06 to 192a09c Compare July 17, 2026 08:11

eisenwave mentioned this pull request Jul 17, 2026

[simd.mask.overview] Put content after \recommended onto a separate line #9198

Merged

eisenwave force-pushed the python-checks branch from 192a09c to fbd0c0b Compare July 17, 2026 14:58

eisenwave added 8 commits July 25, 2026 06:38

Implement Python checks

9dcbe96

Upgrade pyright to Python 3.12

6d4a54c

Modernize type annotations

9f2e23e

Put lookup tables into separate file

017ddec

Add new commands

fe02c01

Disable library checks in UB/IFNDR annexes

c0c5e23

Remove unnecessary pass

1e73cea

Simplify if statement to max

270d416

eisenwave force-pushed the python-checks branch from fbd0c0b to 270d416 Compare July 25, 2026 04:44

eisenwave added 8 commits July 25, 2026 06:51

Remove unnecessary trailing comments

8daba1d

Simplify exit code computation

1a5fc29

Move space into preceding string

35ed7e7

Fix typos for base-tcode-exposid expectations

e20070e

Ignore common Python files

4513a75

Clean code around col1 and col2

5111413

Remove unnecessary begin_pattern and end_pattern variables

665dbe0

Fix Ruff default warnings

7cbded1

1. Nested if statements get flagged. These are replaced with "and". 2. Mutable default initializers for members are flagged. Initialization is moved to __init__.

eisenwave added 8 commits July 25, 2026 09:52

Rename id->uid, manage properly in derived classes

c48c2dd

Convert find_env_ranges to coroutine

388e42c

Eliminate global state

7af3d56

Simplify read_file

33b9379

Eliminate uses for os.path.relpath

147575e

Clean up NOCHECK directive handling in run_checks

0cebc60

Drop ABC

7a03870

Add walkUp=True argument to allow running from source/

9460b52

eisenwave requested review from Tsche, jensmaurer and tkoeppe July 25, 2026 09:01

Tsche suggested changes Aug 3, 2026

View reviewed changes

Uh oh!

Conversation

eisenwave commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eisenwave commented Jun 17, 2026

Uh oh!

eisenwave commented Jun 17, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eisenwave commented Jun 19, 2026

Uh oh!

Uh oh!

Uh oh!

eisenwave commented Jul 17, 2026

Uh oh!

Tsche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

eisenwave commented Jun 17, 2026 •

edited

Loading