blob: 3539bcd9c6cb3f080b9908a534d6cbb4b6f45d81 [file] [edit]
#!/usr/bin/env python3
# SPDX-FileCopyrightText: The Eigen Authors
# SPDX-License-Identifier: MPL-2.0
"""Advisory style check for added lines, for what clang-tidy cannot say.
Flags the problems that recur in this repository's code reviews and that no
clang-tidy check states: narration-comment verbosity (see the comment rules in
``AGENTS.md``), ``enum`` constant blocks, ``std::integral_constant<bool,...>``,
C++17-and-later constructs in the C++14 trees, ``std::`` math in library
headers where ``numext::`` is required, and SME streaming helpers without a
ZA attribute. In documentation it flags the constructs that fail the blocking
documentation job (``.agents/docs.md``): a ``\\ref`` target followed by a
colon, in Doxygen comments and ``.dox`` pages, and in-page links and GitLab
math in the Markdown files Doxygen reads. Conventions clang-tidy *can* state
live in ``.clang-tidy`` and are checked by ``clang_tidy_hook.py`` against the
same added lines. Only lines a change ADDS are reported, but each file's
complete post-image is lexed so surrounding context — an enclosing block
comment, a Doxygen continuation, a multi-line initializer — is classified
correctly.
The findings are advisory: a flagged construct may be justified, in which
case keep it and state the reason where the construct is.
Modes:
--diff BASE check lines added relative to ``merge-base(BASE, HEAD)``,
including uncommitted changes and untracked source files;
exit 1 if findings
--hook HARNESS run as a PostToolUse hook of Claude Code (claude) or Codex
(codex): read the tool-call JSON from stdin and hand the
findings to the model (agent_hooks.py). After an edit it
checks the text the edit added. After a shell command that
committed it checks the lines the commit added, which is
where a file changed through the shell is first seen.
The hook is registered for this repository in ``.claude/settings.json`` and
``.codex/hooks.json``. Other agents and humans can run the diff mode directly,
e.g. ``python3 scripts/check_style.py --diff origin/master``.
"""
import argparse
import fnmatch
import functools
import json
import os
import re
import sys
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from agent_hooks import add_hook_arguments, answer, tool_calls # noqa: E402
from style_common import (REPO_ROOT, added_lines_from_diff, added_from_structured_patch, # noqa: E402,F401
diff_added_lines, hook_added_line_numbers, hook_commit_added, hook_edit_snippets,
hook_post_image_and_added, is_cxx_path, read_post_image)
# Trees whose headers and tests must compile as C++14 (see AGENTS.md rule 3).
# unsupported/Eigen/ is kept for the legacy umbrella shims that still live there;
# the implementation tree itself is contrib/.
CXX14_TREES = ("Eigen/", "contrib/Eigen/", "unsupported/Eigen/", "test/", "contrib/test/", "failtest/", "blas/",
"lapack/")
# Guarded exceptions with a documented newer requirement: SYCL sources build
# only in the C++17 SYCL configurations, while duccfft and the structured-
# binding failtests explicitly select C++17 in their test CMakeLists files.
CXX17_PREFIXES = ("Eigen/src/Core/arch/SYCL/",)
CXX17_FILES = {
"test/sycl_basic.cpp",
"contrib/Eigen/src/FFT/duccfft_impl.h",
"contrib/test/duccfft.cpp",
"failtest/structured_bindings_dynamic_matrix.cpp",
"failtest/structured_bindings_dynamic_array.cpp",
"failtest/structured_bindings_rowmajor.cpp",
}
# Library implementation headers, where numext:: is required over std:: math.
LIBRARY_SRC_TREES = ("Eigen/src/", "contrib/Eigen/src/")
# Clang 23+ will not inline a private-ZA function into a caller with ZA state, and the compilers CI
# builds SME with inline it regardless, so only this check sees a helper that lacks a ZA attribute.
# clang-format keeps the attribute list on the declarator's last line, so one line carries them all.
SME_ARCH_TREE = "Eigen/src/Core/arch/SME/"
SME_ZA_CHECK = (
r"^(?!.*(?:\b__arm_(?:in(?:out)?|out|preserves|new|agnostic)\s*\(|\bEIGEN_SME_ZA_AGNOSTIC\b))"
r".*\b__arm_streaming(?:_compatible)?\b",
"SME streaming function without a ZA attribute: Clang 23+ will not inline it into a caller with ZA "
"state; add EIGEN_SME_ZA_AGNOSTIC (arch/SME/PacketMath.h) or a shared-ZA attribute")
DOXYGEN = re.compile(r"^\s*(/\*\*|/\*!|///|//!)")
LICENSE = re.compile(r"SPDX|Copyright|License|Mozilla Public", re.I)
# A bibliography is provenance, which AGENTS.md keeps, and it is long by nature: one entry per
# work cited already exceeds the block threshold. Matched on the block's own header line so that
# ordinary prose mentioning a reference is still counted.
REFERENCES = re.compile(r"^\s*(?://|/\*)?\s*References:\s*$", re.M)
STD_MATH = (
r"abs|arg|conj|real|imag|sqrt|cbrt|isnan|isinf|isfinite|signbit|exp|exp2|expm1|log|log1p|log2|pow|"
r"sin|cos|tan|asin|acos|atan|atan2|asinh|acosh|atanh|sinh|cosh|tanh|hypot|fma|copysign|ldexp|floor|"
r"ceil|round|rint|trunc|fmod"
)
# Convention checks applied per added code line (comments and literals blanked).
#
# Only conventions clang-tidy cannot currently state belong here; NULL and
# typedef moved to modernize-use-nullptr and modernize-use-using in
# .clang-tidy, which clang_tidy_hook.py and ci/scripts/run-clang-tidy.sh run
# against the same added lines. The entries below are the remainder: those
# needing a CustomChecks query (parked in .clang-tidy until CI's clang-tidy
# reaches 22) and those no AST matcher reaches at all.
#
# One known gap in that handover: modernize-use-using in clang-tidy 18 (the
# checkformat:clangtidy toolchain) reports typedefs at class and namespace
# scope but not function-local ones (measured — Block.h 17 of 18, Redux.h 24
# of 25, GeneralMatrixMatrix.h 21 of 28). That was an upstream defect,
# llvm/llvm-project#72179, fixed in the 19.x release, so the gap closes when
# the CI image's clang-tidy moves; until then a function-local typedef in new
# code goes unreported. Reintroducing a regex for it would bring back the
# false positives this handover removes. modernize-use-nullptr has no gap.
CODE_CHECKS = [
# Awaiting the parked eigen-bool-constant query.
(r"std::integral_constant<\s*bool\b", "std::integral_constant<bool,...>: use Eigen's bool_constant (Meta.h)"),
# Awaiting the parked eigen-enum-constant query. No stock check states
# this rule: cppcoreguidelines-use-enum-class asks for `enum class`,
# whereas Eigen wants static constexpr for trait constants.
(r"^\s*enum\s*(?::[^{}]+)?\{", "enum constant block: trait/evaluator constants are static constexpr in new "
"code; Flags is `unsigned int`"),
]
CXX14_CHECKS = [
# Awaiting the parked eigen-if-constexpr query. A C++14 build does not
# reliably reject this on its own: clang accepts `if constexpr` as an
# extension and only warns under -Wc++17-extensions.
(r"\bif\s+constexpr\b", "if constexpr: supported code compiles as C++14; use EIGEN_IF_CONSTEXPR (...) with a "
"condition that is valid either way"),
# These do fail the default C++14 build; flagging them at edit time just
# shortens the loop, and covers headers no built target happens to include.
(r"\bstd::(any|span|optional|variant|string_view|byte|filesystem|void_t)\b",
"C++17/20 library facility: the supported baseline is C++14"),
]
# Also C++14-tree only (CMakeLists.txt defaults CMAKE_CXX_STANDARD to 14), and
# not expressible as a matcher — designated initializers do not parse in C++14,
# so there is no AST for a check to match.
DESIGNATED_MSG = "designated initializer: C++20-only; use aggregate assignment with /*name=*/ comments"
# Documentation checks. Each construct fails build:linux:docs, which no default
# merge request pipeline runs, so it otherwise surfaces on master after the merge.
REF_COLON = (
r"[\\@]ref\s+~?\w+(?:::~?\w+)*(?:\(\))?:(?=\s|$)",
"\\ref target followed by a colon: Doxygen reads the colon as part of the name, and the unresolved "
"reference fails the docs build; follow the target with a space, comma, or period")
IN_PAGE_LINK = re.compile(r"\]\(#([^)\s]*)\)")
IN_PAGE_LINK_MSG = ("in-page link in Markdown that Doxygen reads: [text](#heading) is an unresolved \\ref, which "
"fails the docs build, unless the heading carries that id as {#id}")
HEADING_ID = re.compile(r"\{#([\w-]+)\}|[\\@]anchor\s+([\w-]+)")
GITLAB_MATH = (r"\$`", "GitLab math in Markdown that Doxygen reads: Doxygen does not render it and can fail on it; "
"write the file for Doxygen or add it to EXCLUDE in doc/Doxyfile.in")
# Doxygen's inputs (EIGEN_DOXY_INPUT in doc/CMakeLists.txt); FILE_PATTERNS is *.
DOXYGEN_INPUT_TREES = ("doc/", "Eigen/", "contrib/doc/", "contrib/Eigen/")
RAW_PREFIX = re.compile(r"(?:^|[^0-9A-Za-z_])(?:u8|u|U|L)?R$")
def is_digit_separator(line, i):
"""Return whether the apostrophe at ``i`` belongs to a C++ number."""
if i + 1 >= len(line) or not line[i + 1].isalnum():
return False
start = i
while start > 0 and (line[start - 1].isalnum() or line[start - 1] in "._'"):
start -= 1
token = line[start:i]
return bool(token) and (token[0].isdigit() or (len(token) > 1 and token[0] == "." and token[1].isdigit()))
def scan_quoted(line, j, quote):
"""Scan a quoted literal's remainder from position ``j``.
Returns (next_position, closed, spliced): ``spliced`` is True when the
line ends with a backslash inside the literal, so the literal continues
on the next physical line.
"""
n = len(line)
while j < n:
if line[j] == "\\":
if j == n - 1:
return n, False, True
j += 2
continue
if line[j] == quote:
return j + 1, True, False
j += 1
return n, False, False
def lex_lines(lines):
"""Lex a file's complete contiguous text.
Returns (code_lines, comment_only, doxygen_only) as parallel lists: per
line, the code with comments and string/character literals blanked, the
stripped comment text when the line holds no code (else None), and whether
that comment belongs to Doxygen. Block comments, raw string literals, and
backslash-spliced ordinary literals carry their state across physical
lines.
"""
code_lines, comment_only, doxygen_only = [], [], []
in_block = False
block_doxygen = False
raw_terminator = None # e.g. )delim" while inside a raw string literal
open_quote = None # quote character of a spliced ordinary literal
for line in lines:
out, i, n = [], 0, len(line)
had_code = False
had_comment = in_block
line_doxygen = block_doxygen if in_block else False
literal_at_start = raw_terminator is not None or open_quote is not None
while i < n:
if in_block:
j = line.find("*/", i)
if j < 0:
i = n
else:
in_block = False
block_doxygen = False
i = j + 2
continue
if raw_terminator is not None:
j = line.find(raw_terminator, i)
if j < 0:
i = n
else:
i = j + len(raw_terminator)
raw_terminator = None
continue
if open_quote is not None:
i, closed, spliced = scan_quoted(line, i, open_quote)
if closed or not spliced: # an unspliced open literal is ill-formed; close at EOL
open_quote = None
continue
c = line[i]
if c == "/" and i + 1 < n and line[i + 1] == "/":
had_comment = True
line_doxygen = line_doxygen or bool(DOXYGEN.match(line[i:]))
break
if c == "/" and i + 1 < n and line[i + 1] == "*":
had_comment = True
block_doxygen = line.startswith(("/**", "/*!"), i)
line_doxygen = line_doxygen or block_doxygen
in_block = True
i += 2
continue
if c == '"' and RAW_PREFIX.search(line[:i]):
paren = line.find("(", i + 1)
delimiter = line[i + 1:paren] if paren >= 0 else None
if delimiter is not None and len(delimiter) <= 16 and not re.search(r"[()\\\s]", delimiter):
out.append('""')
had_code = True
raw_terminator = ")" + delimiter + '"'
j = line.find(raw_terminator, paren + 1)
if j < 0:
i = n
else:
i = j + len(raw_terminator)
raw_terminator = None
continue
if c == "'" and is_digit_separator(line, i):
# C++14 digit separator inside a preprocessing-number, not a
# character-literal delimiter (for example 1'000 or 0xFF'00).
out.append(c)
had_code = True
i += 1
continue
if c in "\"'":
out.append(c + c)
had_code = True
i, closed, spliced = scan_quoted(line, i + 1, c)
if not closed and spliced:
open_quote = c
continue
out.append(c)
if not c.isspace():
had_code = True
i += 1
stripped = line.strip()
is_comment = (not had_code) and had_comment and not literal_at_start
code_lines.append("".join(out))
comment_only.append(stripped if is_comment else None)
doxygen_only.append(line_doxygen if is_comment else None)
return code_lines, comment_only, doxygen_only
def check_comments(comment_only, doxygen_only, added, findings):
"""Flag comment blocks that gain six or more added narration lines.
Blocks are formed over the full file, so an addition inside an existing
Doxygen, license or bibliography block inherits that block's exemption, and
only the ADDED lines count toward the threshold — extending a pre-existing
block by a line or two is not reported.
"""
def finish_block(block_start, block_end, is_doxygen):
block = comment_only[block_start:block_end]
added_in_block = [line_no for line_no in range(block_start + 1, block_end + 1) if line_no in added]
text = "\n".join(block)
exempt = is_doxygen or LICENSE.search(text) or REFERENCES.search(text)
if added_in_block and len(added_in_block) >= 6 and not exempt:
findings.append((added_in_block[0], "%d added lines of non-Doxygen comment: AGENTS.md keeps only "
"mathematics, invariants, compatibility constraints, provenance, "
"or the reason a deliberate construct must not be simplified"
% len(added_in_block)))
block_start, block_doxygen = None, None
for idx in range(len(comment_only) + 1):
comment = comment_only[idx] if idx < len(comment_only) else None
if comment is not None:
if block_start is None:
block_start = idx
block_doxygen = doxygen_only[idx]
elif doxygen_only[idx] != block_doxygen:
finish_block(block_start, idx, block_doxygen)
block_start = idx
block_doxygen = doxygen_only[idx]
elif block_start is not None:
finish_block(block_start, idx, block_doxygen)
block_start = None
def check_designated_initializer(code_lines, line_no, findings):
code = code_lines[line_no - 1]
hit = re.search(r"[{,]\s*\.\w+\s*=", code)
if not hit and re.match(r"\s*\.\w+\s*=", code):
# A line-leading designator continues a braced initializer only when
# the previous code line ends with `{` or `,`; anything else is a
# wrapped member access or assignment.
for prev in range(line_no - 2, -1, -1):
prev_code = code_lines[prev].rstrip()
if prev_code:
hit = prev_code.endswith("{") or prev_code.endswith(",")
break
if hit:
findings.append((line_no, DESIGNATED_MSG))
return True
return False
def check_conventions(rel_path, code_lines, added, findings):
checks = list(CODE_CHECKS)
cxx17_path = (
rel_path in CXX17_FILES
or rel_path.startswith(CXX17_PREFIXES)
or (rel_path.startswith("contrib/Eigen/src/Tensor/") and rel_path.endswith("Sycl.h"))
or (rel_path.startswith("contrib/test/") and rel_path.endswith("_sycl.cpp"))
)
if rel_path.startswith(CXX14_TREES) and not cxx17_path:
checks += CXX14_CHECKS
if rel_path.startswith(LIBRARY_SRC_TREES):
checks.append((r"(?:\(\s*)?\bstd::(?:%s)\s*(?:\)\s*)?\(" % STD_MATH,
"std:: math call in a library header: use the numext:: equivalent "
"(device- and custom-scalar-aware)"))
checks.append((r"(?:\(\s*)?\bstd::frexp\s*(?:\)\s*)?\(",
"std::frexp call in a library header: use EIGEN_USING_STD(frexp) and an unqualified call "
"for ADL and device/custom-scalar support"))
if rel_path.startswith(SME_ARCH_TREE):
checks.append(SME_ZA_CHECK)
added_sorted = sorted(added)
for pattern, message in checks:
rx = re.compile(pattern)
for line_no in added_sorted:
if rx.search(code_lines[line_no - 1]):
findings.append((line_no, message))
break # one report per pattern per file
for line_no in added_sorted:
if check_designated_initializer(code_lines, line_no, findings):
break
def doxygen_excludes(doxyfile_text):
"""Return (paths, patterns): the repository-relative paths in ``EXCLUDE``
and the wildcards in ``EXCLUDE_PATTERNS`` of a ``doc/Doxyfile.in``."""
values = {"EXCLUDE": [], "EXCLUDE_PATTERNS": []}
key = None # the key a continued line belongs to
for raw in doxyfile_text.splitlines():
line = raw.strip()
match = re.match(r"(EXCLUDE|EXCLUDE_PATTERNS)\s*=\s*(.*)$", line)
if match:
key, line = match.groups()
elif key is None:
continue
values[key].extend(line.rstrip("\\").split())
if not line.endswith("\\"):
key = None
paths = [value.replace("${Eigen_SOURCE_DIR}/", "") for value in values["EXCLUDE"]]
return paths, values["EXCLUDE_PATTERNS"]
def is_doxygen_markdown(rel_path, excludes):
"""Return whether Doxygen reads the Markdown file ``rel_path``, given
``excludes`` as ``doxygen_excludes`` returns them."""
if not rel_path.endswith(".md") or not rel_path.startswith(DOXYGEN_INPUT_TREES):
return False
paths, patterns = excludes
if any(rel_path == path or rel_path.startswith(path + "/") for path in paths):
return False
name = os.path.basename(rel_path)
return not any(fnmatch.fnmatch(name, pattern) or fnmatch.fnmatch(rel_path, pattern) for pattern in patterns)
@functools.cache
def repository_doxygen_excludes():
return doxygen_excludes(read_post_image(REPO_ROOT, "doc/Doxyfile.in") or "")
def check_patterns(checks, texts, added, findings):
"""Report the first added line each pattern matches; ``texts[n - 1]`` is
line ``n``'s text, or None where the check does not apply."""
for pattern, message in checks:
rx = re.compile(pattern)
for line_no in sorted(added):
if texts[line_no - 1] is not None and rx.search(texts[line_no - 1]):
findings.append((line_no, message))
break
def check_markdown(lines, added, findings):
"""Flag GitLab math and in-page links to an undeclared id on added lines
outside fenced code blocks."""
texts, fenced = [], False
for line in lines:
fence = line.lstrip().startswith(("```", "~~~"))
fenced = fenced != fence
texts.append(None if fenced or fence else line)
check_patterns([GITLAB_MATH], texts, added, findings)
ids = set()
for text in texts:
for heading_id, anchor in HEADING_ID.findall(text or ""):
ids.add(heading_id or anchor)
for line_no in sorted(added):
targets = IN_PAGE_LINK.findall(texts[line_no - 1] or "")
if any(target not in ids for target in targets):
findings.append((line_no, IN_PAGE_LINK_MSG))
break
def find_findings(rel_path, lines, added, excludes=None):
"""Check one file: ``lines`` is the complete post-image, ``added`` the set
of 1-based line numbers the change added. Returns [(line_no, message)]."""
added = {n for n in added if 1 <= n <= len(lines) and lines[n - 1].strip()}
if not added:
return []
findings = []
if is_cxx_path(rel_path):
code_lines, comment_only, doxygen_only = lex_lines(lines)
check_comments(comment_only, doxygen_only, added, findings)
check_conventions(rel_path, code_lines, added, findings)
doxygen = [text if is_doxygen else None for text, is_doxygen in zip(comment_only, doxygen_only)]
check_patterns([REF_COLON], doxygen, added, findings)
elif rel_path.endswith(".dox"):
check_patterns([REF_COLON], lines, added, findings)
elif is_doxygen_markdown(rel_path, repository_doxygen_excludes() if excludes is None else excludes):
check_markdown(lines, added, findings)
findings.sort()
return findings
def check_files(per_file, root=REPO_ROOT, rev=None):
"""Return [(rel_path, line_no, message)] for {rel_path: added line numbers},
reading each file from the work tree, or from commit ``rev`` when given."""
results = []
for rel_path in sorted(per_file):
text = read_post_image(root, rel_path, rev)
if text is None: # deleted or unreadable
continue
for line_no, message in find_findings(rel_path, text.splitlines(), per_file[rel_path]):
results.append((rel_path, line_no, message))
return results
def run_diff_mode(base, root=REPO_ROOT):
"""Return [(rel_path, line_no, message)] for lines added since
merge-base(base, HEAD), including untracked source files."""
return check_files(diff_added_lines(base, root), root)
def run_hook_mode(harness="claude"):
try:
payload = json.load(sys.stdin)
except Exception:
return 0
feedback = []
for call in tool_calls(harness, payload):
for root, per_file in hook_commit_added(call, hook="check-style"):
results = check_files(per_file, root, rev="HEAD")
if results:
feedback.append("style check (lines added by the commit in %s) — review before proceeding:\n" % root)
feedback.extend(" - %s:%d: %s\n" % result for result in results[:8])
rel_path, snippets = hook_edit_snippets(call)
if rel_path is None:
continue
# The hook runs after the edit, so the file on disk is the post-image; it is
# lexed whole so enclosing comments and initializers classify correctly.
lines, added, _ = hook_post_image_and_added(call, rel_path, snippets)
findings = find_findings(rel_path, lines, added)
if findings:
feedback.append("style check (%s) — review before proceeding:\n" % rel_path)
feedback.extend(" - %s\n" % message for _, message in findings[:8])
if feedback:
feedback.append("Advisory: keep a flagged construct only if it is justified, and say why at the construct.\n")
return answer(harness, "".join(feedback))
def main():
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
mode = parser.add_mutually_exclusive_group(required=True)
mode.add_argument("--diff", metavar="BASE", help="check lines added relative to merge-base(BASE, HEAD)")
add_hook_arguments(mode)
args = parser.parse_args()
if args.hook:
try:
return run_hook_mode(args.hook)
except Exception:
return 0 # a broken hook must not block the harness
results = run_diff_mode(args.diff)
for rel_path, line_no, message in results:
print("%s:%d: %s" % (rel_path, line_no, message))
if results:
print("\n%d advisory finding(s) in added lines. Keep a flagged construct only if it is justified, "
"and say why at the construct." % len(results))
return 1 if results else 0
if __name__ == "__main__":
sys.exit(main())