refactoring: speedup static checks with disk cache

[tarekziade]

What does this PR do?

make check-repo can be quite slow, this patch adds file-level cache to speed up checks.

We get up to a 27x speedup

• cold cache : 46s
• warm cache : 1.6s

[HuggingFaceDocBuilderDev]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[ydshieh]

as discussed on slack, let's separate the PR into multiple ones :-)

For check_docstrings, it would be nice to add some short docstring for each newly added test in tests/repo_utils/test_check_docstrings.py, like

    def test_ignores_other_decorators(self):
        """ what this really want to check (and maybe also why it should be the expected output you specified) """
        path = self._write_temp("@dataclass\nclass Baz:\n    pass\n")
        names = _get_auto_docstring_names(path)
        self.assertEqual(names, set())

(I don't mind AI generate docstring, as long as you have an 👀 reading it first 🙏 )

For some tests, we could guess what they are from the test body, but it's not always clear.

(I know, we rarely have docstring in test methods ... in general 😢 )

[tarekziade]

splited out the doctsring refactoring in a different PR #45009

[tarekziade]

splitted out changes to check_repo in #45012

[ydshieh]

Very nice and thank you for the iteration! Going to 🚀

[ydshieh]

Thanks for the work, this is a nice speedup!

One concern: CHECKER_FILE_GLOBS in checkers.py is a manually maintained map that approximates what each checker script actually scans internally. But each checker has its own file discovery logic, and there's no guarantee these globs stay in sync with it. If a checker script starts scanning additional files and CHECKER_FILE_GLOBS isn't updated accordingly, the cache will silently say "current" and skip the checker — meaning a real issue goes undetected with no warning.

It's also not clear from the code whether these globs are a faithful 1:1 replication of each checker's internal file discovery, or just a best-effort approximation. If approximations, this fragility should at least be prominently documented.

[tarekziade]

Thanks for the work, this is a nice speedup!

One concern: CHECKER_FILE_GLOBS in checkers.py is a manually maintained map that approximates what each checker script actually scans internally. But each checker has its own file discovery logic, and there's no guarantee these globs stay in sync with it. If a checker script starts scanning additional files and CHECKER_FILE_GLOBS isn't updated accordingly, the cache will silently say "current" and skip the checker — meaning a real issue goes undetected with no warning.

It's also not clear from the code whether these globs are a faithful 1:1 replication of each checker's internal file discovery, or just a best-effort approximation. If approximations, this fragility should at least be prominently documented.

Thanks, that’s a very good point, and I agree the failure mode here is particularly risky since it can silently skip checks. I like the idea of reducing the chance of drift by moving the glob definition next to each checker, so the file discovery logic and the cache inputs live in the same place. That should make changes much harder to miss.

I’ll also double-check whether these globs are currently a strict reflection of each checker’s behavior or just approximations. If there’s any approximation involved, I’ll make that explicit in the code and add documentation calling out the risk.

Longer term, it might be worth exploring whether we can derive the inputs directly from the checker logic instead of duplicating it, to avoid this class of issue entirely.

[tarekziade]

I should also add that there are no cache on CI side so we will not miss a check failure prior to merging

[ydshieh]

Just a few nit, then we can go!

Super nice 🔥