From b9f041cabc2d2e30963f8690795c3d7fb0014ebc Mon Sep 17 00:00:00 2001 From: dayfine Date: Fri, 30 Oct 2026 00:50:10 -0700 Subject: [PATCH 1/2] Code health: skip nested and detail classes in the single-method interface check A class nested in another class, or in a detail or anonymous namespace, is an implementation detail such as a type-erasure base, not an interface others implement. MoveOnlyFunction's private Callable base was flagged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E --- devtools/code_health/classes.py | 20 ++++++++++++++++++-- devtools/code_health/tests/test_classes.py | 14 ++++++++++++++ 2 files changed, 32 insertions(+), 2 deletions(-) diff --git a/devtools/code_health/classes.py b/devtools/code_health/classes.py index d84622d691..50acb4d591 100644 --- a/devtools/code_health/classes.py +++ b/devtools/code_health/classes.py @@ -43,6 +43,7 @@ class ClassInfo: line: int has_bases: bool members: tuple + internal: bool = False # nested in a class, or in a detail or anonymous namespace def tokens(source): @@ -264,6 +265,16 @@ def scope_label(toks, index, heads): return None +def is_internal_scope(toks, index, heads): + """A '{' that opens a class, an anonymous namespace or a detail namespace.""" + if index in heads: + return True + if index > 0 and toks[index - 1][0] == 'namespace': + return True + label = scope_label(toks, index, heads) or '' + return label == 'detail' or label.endswith('::detail') + + def find_classes(source): toks = tokens(source) pairs = brace_pairs(toks) @@ -273,7 +284,7 @@ def find_classes(source): head = class_head(toks, index) if head and head[0] and head[2] in pairs: heads[head[2]] = (head[0], head[1], line, text) - result, stack = [], [] + result, stack, internal = [], [], [] for index, (text, _) in enumerate(toks): if text == '{': label = scope_label(toks, index, heads) @@ -282,14 +293,19 @@ def find_classes(source): body = members(toks, index + 1, pairs[index], pairs, keyword, name) if body is not None: qualified = '::'.join([s for s in stack if s] + [name]) - result.append(ClassInfo(qualified, line, bases, tuple(body))) + result.append(ClassInfo(qualified, line, bases, tuple(body), any(internal))) stack.append(label) + internal.append(is_internal_scope(toks, index, heads)) elif text == '}' and stack: stack.pop() + internal.pop() return result def is_single_method_interface(info): + """Nested and detail-namespace classes are implementation details (e.g. type erasure).""" + if info.internal: + return False methods = [m for m in info.members if m.kind == 'method'] others = [m for m in info.members if m.kind != 'method' and not (m.kind == 'dtor' and m.virtual)] diff --git a/devtools/code_health/tests/test_classes.py b/devtools/code_health/tests/test_classes.py index 43ff454251..94402641a8 100644 --- a/devtools/code_health/tests/test_classes.py +++ b/devtools/code_health/tests/test_classes.py @@ -31,6 +31,20 @@ def test_single_method_interface(self): with self.subTest(source=source): self.assertEqual(0, values(source)['single_method_interface']) + def test_single_method_interface_skips_implementation_details(self): + nested = ('class F{\nprivate:\n class Callable{\n public:\n virtual ~Callable() = default;\n' + ' virtual void call() = 0;\n };\n Callable* m_impl;\n};') + self.assertEqual(0, values(nested, 'F::Callable')['single_method_interface']) + for source in ('namespace{ struct L{ virtual void on() = 0; }; }', + 'namespace a{ namespace detail{ struct L{ virtual void on() = 0; }; } }', + 'namespace a::detail{ struct L{ virtual void on() = 0; }; }'): + with self.subTest(source=source): + self.assertEqual(0, values(source)['single_method_interface']) + for source in ('namespace a{ struct L{ virtual void on() = 0; }; }', + 'namespace a::b{ struct L{ virtual void on() = 0; }; }'): + with self.subTest(source=source): + self.assertEqual(1, values(source)['single_method_interface']) + def test_public_method_count_excludes_special_members(self): extra = (' A();\n A(const A&) = delete;\n ~A();\n A& operator=(A&&);\n' ' operator bool() const;\n void gone() = delete;\nprivate:\n void hidden();\npublic:\n') From 97039fd7e8587473dbc4fb5cc384f6eb652445cf Mon Sep 17 00:00:00 2001 From: dayfine Date: Sat, 31 Oct 2026 12:16:31 -0700 Subject: [PATCH 2/2] Code health: lexical C++ style checks on added lines Check the lines a change adds for the upstream bans (std::filesystem, std::thread, std::mutex, std::async), control-flow brace formatting, and the Abseil tips adopted in the fork's C++ style notes: mutable globals (#103), new/delete (#126), std::bind (#108), return std::move(local) (#120), top-level const by-value header parameters (#109), bool parameters (#94), header using-directives (#153) and forward declarations. A comment that describes a neighbouring function is an advisory. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01AKYzhrMnPK61XHWEch4a6E --- devtools/code_health/README.md | 25 ++ devtools/code_health/__main__.py | 5 +- devtools/code_health/style.py | 511 +++++++++++++++++++++++ devtools/code_health/tests/test_cli.py | 14 + devtools/code_health/tests/test_style.py | 226 ++++++++++ 5 files changed, 780 insertions(+), 1 deletion(-) create mode 100644 devtools/code_health/style.py create mode 100644 devtools/code_health/tests/test_style.py diff --git a/devtools/code_health/README.md b/devtools/code_health/README.md index 49ff95c999..eecceb2ad9 100644 --- a/devtools/code_health/README.md +++ b/devtools/code_health/README.md @@ -73,6 +73,31 @@ module: `Pokemon/`, `PokemonBDSP/` or `VideoGames/` under lists both groups and a test fails when a new top-level directory is in neither. Includes already present at the base are not reported. +## Style (added lines only) + +`style.py` checks only the lines a change adds or edits (a line diff against the +base; every line of a new file), so legacy code in a touched file is not reported. +Comments, string/character literals and preprocessor lines are blanked first, and +a brace-scope stack tells namespace, class and function scope apart. It is a +lexer, not a parser: rules that need types stay in review. + +| Check | Level | Rule | +| --- | --- | --- | +| `std::filesystem` (outside `Common/Cpp/Filesystem/`) | error | upstream AGENTS.md "Filesystem" | +| `std::thread`/`jthread`, `std::*mutex`, `std::condition_variable`, `std::async` (outside `Common/Cpp/Concurrency/`) | error | upstream AGENTS.md "Concurrency"; TotW #197 | +| Control flow: `) {`, `} else`, `else {`, `namespace X {`, brace on the next line, one-line `if`/`for`/`while`/`else` bodies | error | upstream AGENTS.md "Control flow formatting" | +| Non-const namespace-scope variable or `extern` | error | TotW #103 | +| `new` / `delete` expressions (exempt: paths containing `alloc`, files including Qt headers, `operator new/delete`, `= delete`) | error | TotW #126 | +| `std::bind` | error | TotW #108 | +| `return std::move(name);` of a local or by-value/`&&` parameter (not `m_` members or `T&` names) | error | TotW #120 | +| Top-level `const` on a by-value parameter in a header declaration | error | TotW #109 | +| A defaulted `bool` parameter, or 2+ `bool` parameters (not `override`/`final`, not an unchanged signature) | error | TotW #94 | +| `using namespace` at namespace scope in a header | error | TotW #153 | +| Forward `class`/`struct` declaration in a header: new header / existing header | error / advisory | fork AGENTS.md "Forward declarations" | +| A comment whose first sentence describes the neighbouring function, none of its own | advisory | CONTRIBUTING; Google "Function Comments" | + +Advisories print as `Advisory:` lines and `::warning` annotations and never fail. + ## Build and native C++ tests in one command The existing `.github/workflows/cpp-ci-serial-programs-base.yml` already runs diff --git a/devtools/code_health/__main__.py b/devtools/code_health/__main__.py index 8eff799750..0536c28f01 100644 --- a/devtools/code_health/__main__.py +++ b/devtools/code_health/__main__.py @@ -5,7 +5,7 @@ import sys from pathlib import Path -from . import layering +from . import layering, style from .classes import measure_classes from .findings import annotations from .git_files import changed_files, default_base, read_revision @@ -32,6 +32,9 @@ def run(root, base_ref=None, github=False): failures.extend(layering.check(current, source, previous_source)) failures.extend(evaluate(metrics, previous)) notes.extend(advisories(metrics, previous)) + style_errors, style_notes = style.check(current, source, previous_source) + failures.extend(style_errors) + notes.extend(style_notes) advisory += sum(m.check == 'file_lines' and 500 < m.value <= 1000 for m in metrics) print(f'Scanned {len(changes)} changed C++ files against {base_ref}.') print(f'Advisory: {advisory} changed files exceed 500 lines; prefer functions <=25 lines.') diff --git a/devtools/code_health/style.py b/devtools/code_health/style.py new file mode 100644 index 0000000000..c403503b7a --- /dev/null +++ b/devtools/code_health/style.py @@ -0,0 +1,511 @@ +"""Lexical C++ style checks on the lines a change adds. + +Upstream bans and formatting rules (AGENTS.md / CONTRIBUTING.md) and the Abseil Tips of +the Week adopted in the fork's C++ style notes. Only added or changed lines are checked, +so legacy code in a touched file is not reported. Comments, string and character +literals and preprocessor lines are blanked before matching. This is a lexer with a +brace-scope stack, not a parser: rules that need types stay in review. +""" +import difflib +import re +from dataclasses import dataclass + +from .findings import Finding + + +HEADERS = ('.h', '.hpp', '.tpp') + + +@dataclass(frozen=True) +class Statement: + text: str # code with whitespace collapsed, attributes removed + line: int # line of its first character + end: str # ';', '{' or '}' + scope: tuple # enclosing brace kinds: 'namespace', 'class', 'enum', 'other' + follows: str = '' # kind of the brace closed just before it: `struct{...} name;` + + @property + def namespace_scope(self): + return all(kind == 'namespace' for kind in self.scope) + + @property + def declaration_scope(self): + """Namespace or class scope: declarations, not statements in a body.""" + return all(kind in ('namespace', 'class') for kind in self.scope) + + +# ---- Lexing ---------------------------------------------------------------------- + +RAW_STRING = re.compile(r'(?:u8|u|U|L)?R"([^()\\\s]{0,16})\(') + + +DIGIT_SEPARATOR = re.compile(r"(? 0 and (source[i - 1].isalnum() or source[i - 1] == '_') + + +def blank(text): + return re.sub(r'[^\n]', ' ', text) + + +def strip_code(source): + """Lines of `source` with comments, literal contents and preprocessor lines blanked. + + Columns and line numbers are kept; quotes stay so `extern "C"` remains recognizable.""" + out, i, n = [], 0, len(source) + while i < n: + c = source[i] + if source.startswith('//', i): + end = source.find('\n', i) + end = n if end < 0 else end + out.append(blank(source[i:end])) + i = end + elif source.startswith('/*', i): + end = source.find('*/', i + 2) + end = n if end < 0 else end + 2 + out.append(blank(source[i:end])) + i = end + elif c in 'uULR' and RAW_STRING.match(source, i) and not identifier_before(source, i): + raw = RAW_STRING.match(source, i) + close = ')' + raw.group(1) + '"' + end = source.find(close, raw.end()) + end = n if end < 0 else end + len(close) + out.append('"' + blank(source[i + 1:end - 1]) + '"') + i = end + elif c == '\'' and DIGIT_SEPARATOR.search(source, max(0, i - 40), i): + out.append(c) # 1'000 + i += 1 + elif c in '"\'': + j = i + 1 + while j < n and source[j] != c and source[j] != '\n': + j += 2 if source[j] == '\\' else 1 + j = min(j + 1, n) + out.append(c + blank(source[i + 1:j - 1]) + source[j - 1:j] if j - 1 > i else c) + i = j + else: + out.append(c) + i += 1 + lines = ''.join(out).split('\n') + continued = False + for index, line in enumerate(lines): + if continued or line.lstrip().startswith('#'): + continued = line.rstrip().endswith('\\') + lines[index] = blank(line) + return lines + + +def brace_kind(text): + if re.search(r'\bnamespace\b[\w:\s]*$', text) or re.fullmatch(r'extern\s*"\s*"', text): + return 'namespace' + if re.match(r'(template\s*<.*>\s*)?(class|struct|union)\b', text): + return 'class' + if re.match(r'enum\b', text): + return 'enum' + return 'other' + + +def statements(code_lines): + """Split blanked code at ';' (outside parentheses), '{' and '}' with their scopes.""" + result, stack = [], [] + text, start, parens, closed = [], None, 0, '' + + def emit(end): + joined = re.sub(r'\[\[.*?\]\]', ' ', ' '.join(''.join(text).split())).strip() + if joined or end != ';': + result.append(Statement(joined, start or line_number, end, + tuple(k for k, _ in stack), closed)) + return joined + + for line_number, line in enumerate(code_lines, 1): + for c in line: + if c == '{': + kind = brace_kind(emit('{')) + stack.append((kind, parens)) + text, start, parens, closed = [], None, 0, '' + elif c == '}': + emit('}') + closed, parens = stack.pop() if stack else ('', 0) + text, start = [], None + elif c == ';' and parens <= 0: + emit(';') + text, start, closed = [], None, '' + else: + parens += (c == '(') - (c == ')') + if start is None and not c.isspace(): + start = line_number + text.append(c) + text.append(' ') + return result + + +def added_lines(source_lines, previous_lines): + """1-based numbers of lines in `source_lines` that are new relative to `previous_lines`.""" + if previous_lines is None: + return set(range(1, len(source_lines) + 1)) + added = set() + matcher = difflib.SequenceMatcher(None, previous_lines, source_lines, autojunk=False) + for tag, _, _, j1, j2 in matcher.get_opcodes(): + if tag in ('replace', 'insert'): + added.update(range(j1 + 1, j2 + 1)) + return added + + +# ---- Signatures -------------------------------------------------------------------- + +NOT_FUNCTIONS = {'if', 'for', 'while', 'switch', 'catch', 'return', 'sizeof', 'alignof', + 'decltype', 'static_assert', 'noexcept', 'alignas', 'requires', 'throw', + 'operator', 'new', 'delete', 'typeid', 'co_return', 'co_await'} + + +def matching(text, open_index, opening='(', closing=')'): + depth = 0 + for k in range(open_index, len(text)): + depth += (text[k] == opening) - (text[k] == closing) + if depth == 0: + return k + return -1 + + +def split_top_level(text): + parts, depth, current = [], 0, [] + for c in text: + if c in '(<[{': + depth += 1 + elif c in ')>]}': + depth -= 1 + if c == ',' and depth == 0: + parts.append(''.join(current).strip()) + current = [] + else: + current.append(c) + tail = ''.join(current).strip() + return parts + [tail] if tail or parts else parts + + +@dataclass(frozen=True) +class Signature: + name: str + params: tuple + tail: str + + +def signature(statement): + """The function a declaration or definition header names, or None.""" + text = statement.text + if statement.end == '}' or not statement.declaration_scope: + return None + if re.match(r'(using|typedef|friend|return|namespace|class|struct|enum|union)\b', text): + return None + for match in re.finditer(r'(~?[A-Za-z_]\w*(?:\s*::\s*~?[A-Za-z_]\w*)*)\s*\(', text): + name = match.group(1).replace(' ', '') + if name.split('::')[-1] in NOT_FUNCTIONS or '=' in text[:match.start()]: + continue + close = matching(text, match.end() - 1) + if close < 0: + return None + tail = text[close + 1:].strip() + if re.search(r'[(=](?!\s*(0|default|delete)\s*$)', tail) and not tail.startswith('->'): + return None + return Signature(name, tuple(split_top_level(text[match.end():close])), tail) + return None + + +def without_templates(text): + while True: + reduced = re.sub(r'<[^<>]*>', '', text) + if reduced == text: + return text + text = reduced + + +def default_split(param): + depth = 0 + for k, c in enumerate(param): + depth += (c in '(<[{') - (c in ')>]}') + if c == '=' and depth == 0 and param[k - 1:k] not in ('=', '!', '<', '>') \ + and param[k + 1:k + 2] != '=': + return param[:k].strip(), param[k + 1:].strip() + return param.strip(), None + + +BOOL_PARAM = re.compile(r'(const\s+)?bool(\s+[A-Za-z_]\w*)?') + + +def bool_params(sig): + return [(p, default) for p, default in map(default_split, sig.params) + if BOOL_PARAM.fullmatch(p)] + + +def top_level_const(param): + declared, _ = default_split(param) + plain = without_templates(declared) + if '&' in plain or '*' in plain or '(' in plain or '...' in plain: + return False + return bool(re.fullmatch(r'const\s+[\w:]+(\s+[\w:]+)*', plain) + or re.fullmatch(r'[\w:]+\s+const(\s+\w+)?', plain)) + + +# ---- Checks ------------------------------------------------------------------------ + +def rule(message, *cites): + return f'style: {message} ({", ".join(cites)})' if cites else f'style: {message}' + + +BANS = ( + (re.compile(r'\bstd::filesystem\b'), ('Common/Cpp/Filesystem/',), + 'std::filesystem is banned; use the Common/Cpp/Filesystem wrappers (Path, Filesystem::, FileIO)', + 'upstream AGENTS.md "Filesystem"'), + (re.compile(r'\bstd::j?thread\b(?!\s*::)'), ('Common/Cpp/Concurrency/',), + 'std::thread is banned; run background work on the pools in GlobalThreadPools.h', + 'upstream AGENTS.md "Concurrency"'), + (re.compile(r'\bstd::(?:(?:recursive_|timed_|recursive_timed_|shared_|shared_timed_)?mutex' + r'|condition_variable(?:_any)?)\b'), ('Common/Cpp/Concurrency/',), + 'std::mutex / std::condition_variable are banned; use PokemonAutomation::Mutex / ConditionVariable', + 'upstream AGENTS.md "Concurrency"', 'TotW #197'), + (re.compile(r'\bstd::async\b'), (), + 'std::async is banned (it may spawn a thread); use the thread pools', + 'upstream AGENTS.md "Concurrency"'), +) +BIND = re.compile(r'\bstd::bind\s*\(') +NEW = re.compile(r'(?]\s*&\s*' + re.escape(name) + r'\b(?!\s*[(.\[])', text)) + + +def line_checks(path, raw, code, added, statements_): + """Bans, expressions and formatting that one line shows.""" + errors = [] + allocator = 'alloc' in path.lower() or bool(QT_INCLUDE.search(raw)) + bodies = [s.line for s in statements_ if s.end == '{' and signature(s)] + for number in sorted(added): + line = code[number - 1] + for pattern, exempt, message, *cites in BANS: + if pattern.search(line) and not path.startswith(exempt or ('\0',)): + errors.append(Finding(path, number, rule(message, *cites))) + if BIND.search(line): + errors.append(Finding(path, number, rule('use a lambda, not std::bind', 'TotW #108'))) + if not allocator and (NEW.search(line) or DELETE.search(line)): + errors.append(Finding(path, number, rule( + 'no new/delete outside allocators; use std::make_unique / std::make_shared', + 'TotW #126'))) + moved = RETURN_MOVE.search(line) + if moved and not moved.group(1).startswith('m_') and not lvalue_reference( + moved.group(1), '\n'.join(code[function_start(bodies, number) - 1:number])): + errors.append(Finding(path, number, rule( + f"don't std::move a returned local ('{moved.group(1)}'); return it by name", + 'TotW #120'))) + errors.extend(Finding(path, number, rule(message, 'upstream AGENTS.md "Control flow formatting"')) + for message in brace_problems(line, code[number] if number < len(code) else '')) + return errors + + +def brace_problems(line, next_line): + problems = [] + if re.search(r'\}[ \t]+else\b|\belse[ \t]+\{', line): + problems.append('write }else{ and }else if (...){ with no spaces around else') + if re.search(r'\bnamespace\b[\w:\s]*?[ \t]+\{', line): + problems.append('write namespace X{ with no space before {') + control = CONTROL.search(line) + if control: + close = matching(line, control.end() - 1) + rest = line[close + 1:].strip() if close >= 0 else None + if rest is None or (control.group(1) == 'while' and rest == ';'): + pass + elif re.match(r'\s+\{', line[close + 1:]): + problems.append(f'no space between ) and {{: {control.group(1)} (...){{') + elif rest == '' and next_line.strip().startswith('{'): + problems.append(f'put the opening brace on the {control.group(1)} line') + elif rest and (not rest.startswith('{') or rest.rstrip('{').strip() or rest.count('}')): + if not (rest.startswith('{') and rest[1:].strip() == ''): + problems.append(f'{control.group(1)} body goes on its own lines, braced') + other_else = re.search(r'\belse\b(?!\s*(if\b|\{|$))', line) + if other_else: + problems.append('else body goes on its own lines, braced') + return problems + + +def is_forward_declaration(statement): + return statement.end == ';' and re.fullmatch( + r'(template\s*<.*>\s*)?(class|struct|union)\s+[A-Za-z_][\w:]*', statement.text) + + +def namespace_variable(statement): + """The name of a non-const variable this namespace-scope statement declares, or None.""" + text = statement.text + if not statement.namespace_scope or statement.end == '}' or statement.follows: + return None + if statement.end == '{' and not text.endswith('='): + if '(' in text or not re.fullmatch(r'[\w:<>,\s\*&]+\s[\*&]*[A-Za-z_]\w*', text): + return None + head = default_split(text.rstrip('=').strip() if statement.end == '{' else text)[0] + if re.match(r'(using|typedef|namespace|template|class|struct|union|enum|friend|static_assert' + r'|return|extern\s*")\b', head) or '(' in without_templates(head): + return None + match = re.fullmatch(r'((?:[\w:]+(?:<.*>)?[\s\*&]+)+?)[\*&\s]*([A-Za-z_]\w*)\s*(\[[^\]]*\])?', head) + if not match: + return None + words = set(re.findall(r'\w+', without_templates(match.group(1)))) + if words & {'const', 'constexpr'} or match.group(2) in ('const', 'constexpr'): + return None + if words <= {'static', 'inline', 'extern', 'thread_local', 'constinit', 'volatile'}: + return None + return match.group(2) + + +def statement_checks(path, statements_, added, previous_signatures, new_file): + errors, warnings = [], [] + header = path.endswith(HEADERS) + # A primary template declared before its specializations is not a forward declaration. + defined = {m.group(1) for s in statements_ if s.end == '{' + for m in [re.search(r'\b(?:class|struct|union)\s+(\w+)', s.text)] if m} + for statement in statements_: + if statement.line not in added: + continue + text = statement.text + if header and statement.namespace_scope and re.match(r'using\s+namespace\b', text): + errors.append(Finding(path, statement.line, rule( + 'no using-directive at namespace scope in a header', 'TotW #153'))) + variable = namespace_variable(statement) + if variable: + what = 'non-const extern' if re.match(r'(static\s+|inline\s+)*extern\b', text) \ + else 'non-const namespace-scope variable' + errors.append(Finding(path, statement.line, rule( + f"{what} '{variable}'; make it const/constexpr or pass options down in a struct", + 'TotW #103'))) + if header and statement.namespace_scope and is_forward_declaration(statement) \ + and text.split()[-1] not in defined: + finding = Finding(path, statement.line, rule( + f"forward declaration '{text}'; include the header that defines it", + 'fork AGENTS.md "Forward declarations"')) + (errors if new_file else warnings).append(finding) + sig = signature(statement) + if sig is None: + continue + if header and statement.end == ';': + for param in sig.params: + if top_level_const(param): + errors.append(Finding(path, statement.line, rule( + f"{sig.name}: drop top-level const from by-value parameter '{param}' " + 'in the declaration', 'TotW #109'))) + bools = bool_params(sig) + defaulted = [p for p, default in bools if default is not None] + if (len(bools) >= 2 or defaulted) and not re.search(r'\b(override|final)\b', sig.tail) \ + and (sig.name, len(bools), len(defaulted)) not in previous_signatures: + problem = 'a defaulted bool parameter' if defaulted else f'{len(bools)} bool parameters' + errors.append(Finding(path, statement.line, rule( + f'{sig.name}: {problem}; use an enum class or an options struct', 'TotW #94'))) + return errors, warnings + + +def bool_signatures(statements_): + result = set() + for statement in statements_: + sig = signature(statement) + if sig: + bools = bool_params(sig) + result.add((sig.name, len(bools), sum(d is not None for _, d in bools))) + return result + + +# ---- Function comments (advisory) ---------------------------------------------------- + +STOP_WORDS = {'the', 'and', 'for', 'from', 'with', 'get', 'set', 'run', 'try', 'all'} + + +def name_tokens(name): + return [t for t in name.split('::')[-1].lower().split('_') if len(t) >= 3 and t not in STOP_WORDS] + + +def prose_words(text): + """(first sentence, rest) of a comment as sets of lowercase words, without code + references (`x`, a_b, f(), A::B).""" + text = re.sub(r'^\s*//+', ' ', text, flags=re.M) + text = re.sub(r'`[^`]*`|\b\w+\(\)|\b\w*_\w*\b|\b\w+::\w+', ' ', text) + parts = re.split(r'(?<=[a-z0-9)])\.(?:\s|$)', text.strip(), maxsplit=1) + [''] + return tuple(set(re.findall(r'[a-z0-9]+', part.lower())) for part in parts[:2]) + + +def mentioned(token, words): + """Whether a word shares the token's stem: berry/berries, add/adds, save/saving.""" + stem = token[:-1] if len(token) >= 4 else token + return any(w.startswith(stem) or (len(w) >= 4 and token.startswith(w)) for w in words) + + +def comment_above(raw_lines, line): + """(first line, text) of the // comment block directly above `line`, or None.""" + k = line - 1 + while k >= 1 and raw_lines[k - 1].strip().startswith('//'): + k -= 1 + if k == line - 1: + return None + return k + 1, '\n'.join(raw_lines[k:line - 1]) + + +def describes(name, words, share=1.0): + tokens = name_tokens(name) + return bool(tokens) and sum(mentioned(t, words) for t in tokens) >= share * len(tokens) + + +def comment_checks(path, raw_lines, statements_, added): + """A comment whose first sentence describes a neighbouring function and none of its own, + when its own function is described later in the block or the neighbour has no comment: + a stale comment left above another, or a comment that slid one function down.""" + functions = [(s.line, signature(s)) for s in statements_] + functions = [(line, sig.name) for line, sig in functions if sig] + warnings = [] + for index, (line, name) in enumerate(functions): + block = comment_above(raw_lines, line) + if block is None or not added & set(range(block[0], line + 1)): + continue + first, rest = prose_words(block[1]) + if any(mentioned(t, first) for t in name_tokens(name)): + continue + for other_line, other in functions[max(0, index - 1):index] + functions[index + 1:index + 2]: + if other == name or len(name_tokens(other)) < 2 or not describes(other, first): + continue + if describes(name, rest, 0.5) or comment_above(raw_lines, other_line) is None: + warnings.append(Finding(path, block[0], rule( + f'this comment sits above {name} but its first sentence describes {other}; ' + 'function comments go directly above their function', + 'CONTRIBUTING', 'Google "Function Comments"'))) + break + return warnings + + +# ---- Entry point ------------------------------------------------------------------- + +def check(path, source, previous_source): + """(errors, warnings) for the style rules on lines this change adds.""" + raw = source.replace('\r\n', '\n').replace('\r', '\n') + raw_lines = raw.split('\n') + previous_lines = None + previous_statements = [] + if previous_source is not None: + previous = previous_source.replace('\r\n', '\n').replace('\r', '\n') + previous_lines = previous.split('\n') + previous_statements = statements(strip_code(previous)) + added = added_lines(raw_lines, previous_lines) + if not added: + return [], [] + code = strip_code(raw) + statements_ = statements(code) + errors = line_checks(path, raw, code, added, statements_) + more_errors, warnings = statement_checks(path, statements_, added, + bool_signatures(previous_statements), + previous_source is None) + warnings += comment_checks(path, raw_lines, statements_, added) + return sorted(errors + more_errors, key=lambda f: f.line), sorted(warnings, key=lambda f: f.line) diff --git a/devtools/code_health/tests/test_cli.py b/devtools/code_health/tests/test_cli.py index 8396ab9a40..fffa637444 100644 --- a/devtools/code_health/tests/test_cli.py +++ b/devtools/code_health/tests/test_cli.py @@ -163,6 +163,20 @@ def test_shared_code_may_not_add_game_includes(self): self.assertEqual(1, result.returncode, result.stderr) self.assertIn('Tool.cpp:1: layering', result.stderr) + def test_style_checks_report_only_added_lines(self): + file = self.root / 'Common/style.cpp' + file.write_text('void f(){\n if (x) return;\n}\n') + self.commit() + file.write_text('void f(){\n if (x) return;\n g();\n}\n') + self.git('add', '.') + self.assertEqual(0, self.cli().returncode) + file.write_text('void f(){\n if (x) return;\n std::mutex m;\n}\n') + self.git('add', '.') + result = self.cli() + self.assertEqual(1, result.returncode, result.stderr) + self.assertIn('style.cpp:3: style: std::mutex', result.stderr) + self.assertNotIn('style.cpp:2:', result.stderr) + def test_github_annotates_failures_and_advisories(self): self.source(3) self.commit() diff --git a/devtools/code_health/tests/test_style.py b/devtools/code_health/tests/test_style.py new file mode 100644 index 0000000000..810524b7f5 --- /dev/null +++ b/devtools/code_health/tests/test_style.py @@ -0,0 +1,226 @@ +import unittest + +from devtools.code_health.style import added_lines, check, strip_code + + +CPP = 'SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/Example.cpp' +HEADER = 'SerialPrograms/Source/VideoGames/PokemonFRLG/Programs/Example.h' + + +def wrap(body): + return 'namespace PokemonAutomation{\nnamespace NintendoSwitch{\n' + body + '\n}\n}\n' + + +def in_function(body): + return wrap('void example(){\n' + body + '\n}') + + +class StyleCase(unittest.TestCase): + def errors(self, source, path=CPP, previous=None): + return [f.message for f in check(path, source, previous)[0]] + + def warnings(self, source, path=CPP, previous=None): + return [f.message for f in check(path, source, previous)[1]] + + def assertFlags(self, fragment, source, path=CPP, count=1): + messages = [m for m in self.errors(source, path) if fragment in m] + self.assertEqual(count, len(messages), self.errors(source, path)) + + def assertClean(self, source, path=CPP): + self.assertEqual([], self.errors(source, path)) + self.assertEqual([], self.warnings(source, path)) + + +class LexingTests(unittest.TestCase): + def test_comments_strings_and_preprocessor_are_blanked(self): + code = strip_code('int a; // new\n/* std::bind(\n */ s = "delete";\n#define X new int\n' + 'r = R"x(std::mutex)x"; c = \'{\'; n = 1\'000;') + self.assertEqual(['int a;', '', ' s = " ";', '', + 'r = " "; c = \' \'; n = 1\'000;'], + [line.rstrip() for line in code]) + + def test_only_inserted_and_replaced_lines_are_added(self): + self.assertEqual({2, 4}, added_lines(['a', 'B', 'c', 'd'], ['a', 'b', 'c'])) + self.assertEqual({1, 2}, added_lines(['a', 'b'], None)) + + +class BanTests(StyleCase): + def test_banned_std_facilities(self): + for line, fragment in (('std::filesystem::path p;', 'std::filesystem is banned'), + ('std::thread worker(run);', 'std::thread is banned'), + ('std::jthread worker(run);', 'std::thread is banned'), + ('std::lock_guard lg(m_lock);', 'std::mutex'), + ('std::shared_mutex m;', 'std::mutex'), + ('std::condition_variable cv;', 'std::mutex'), + ('auto f = std::async(run);', 'std::async is banned')): + with self.subTest(line=line): + self.assertFlags(fragment, in_function(line)) + + def test_allowed_neighbours_and_wrapper_directories(self): + self.assertClean(in_function('std::this_thread::sleep_for(10ms);\n' + 'size_t n = std::thread::hardware_concurrency();\n' + 'Mutex m;\n// std::mutex in a comment\nlog("std::async");')) + self.assertEqual([], self.errors(in_function('std::mutex m;'), 'Common/Cpp/Concurrency/Mutex.h')) + self.assertEqual([], self.errors(in_function('std::filesystem::path p;'), + 'Common/Cpp/Filesystem/Path.cpp')) + + +class ExpressionTests(StyleCase): + def test_std_bind(self): + self.assertFlags('TotW #108', in_function('auto f = std::bind(&run, 1);')) + self.assertClean(in_function('auto f = std::bind_front(&run, 1);\nauto g = [&]{ run(1); };')) + + def test_new_and_delete(self): + self.assertFlags('TotW #126', in_function('Foo* p = new Foo();')) + self.assertFlags('TotW #126', in_function('delete[] p;')) + self.assertClean(wrap('struct A{\n A(const A&) = delete;\n void* operator new(size_t);\n' + ' void operator delete(void*);\n};\n' + 'void f(){\n auto p = std::make_unique();\n}')) + + def test_new_allowed_in_allocators_and_qt_files(self): + self.assertEqual([], self.errors(in_function('T* p = new T();'), 'Common/Cpp/AlignedAllocator.h')) + self.assertEqual([], self.errors('#include \n' + in_function('new QLabel(this);'))) + + def test_return_std_move_of_a_local(self): + self.assertFlags('TotW #120', wrap('Foo f(){\n Foo result;\n return std::move(result);\n}')) + self.assertFlags('TotW #120', wrap('Foo f(Foo&& value){\n return std::move(value);\n}')) + + def test_return_std_move_of_members_and_lvalue_references(self): + self.assertClean(wrap('Foo A::f(){\n return std::move(m_value);\n}\n' + 'Foo g(Foo& value){\n return std::move(value);\n}\n' + 'Foo h(Map& map){\n return std::move(map.begin()->second);\n}')) + + +class FormattingTests(StyleCase): + def test_brace_spacing(self): + for line, fragment in (('if (x) {', 'no space between ) and {'), + ('for (int i = 0; i < n; i++) {', 'no space between ) and {'), + ('}else {', 'no spaces around else'), + ('} else{', 'no spaces around else')): + with self.subTest(line=line): + self.assertFlags(fragment, in_function(line + '\n run();\n}')) + self.assertFlags('namespace X{', 'namespace PokemonAutomation {\n}\n') + self.assertFlags('namespace X{', 'namespace{\n}\nnamespace A::B {\n}\n') + + def test_single_line_bodies_and_next_line_braces(self): + self.assertFlags('if body goes on its own lines', in_function('if (x) return;')) + self.assertFlags('if body goes on its own lines', in_function('if (x){ return; }')) + self.assertFlags('else body goes on its own lines', in_function('if (x){\n a();\n}else b();')) + self.assertFlags('put the opening brace on the while line', + in_function('while (x)\n{\n run();\n}')) + + def test_repo_formatting_passes(self): + self.assertClean(in_function( + 'if (x){\n a();\n}else if (y){\n b();\n}else{\n c();\n}\n' + 'do{\n a();\n}while (x);\n' + 'if (std::any_of(v.begin(), v.end(), [](int i){ return i > 0; })){\n a();\n}\n' + 'if (x &&\n y){\n a();\n}\n' + 'switch (x){\ncase 1:\n break;\n}')) + + +class DeclarationTests(StyleCase): + def test_mutable_namespace_scope_variables(self): + self.assertFlags("non-const namespace-scope variable 'counter'", wrap('int counter = 0;')) + self.assertFlags("'TABLE'", wrap('static std::map TABLE = {\n {1, 2},\n};')) + self.assertFlags("'BOX'", wrap('ImageFloatBox BOX{0.1, 0.2, 0.3, 0.4};')) + self.assertFlags("non-const extern 'g_stop'", wrap('extern bool g_stop;'), HEADER) + + def test_constants_functions_and_locals_pass(self): + self.assertClean(wrap( + 'const int LIMIT = 3;\nconstexpr double SCALE = 1.5;\nextern const ImageFloatBox AREA;\n' + 'static const std::map TABLE = {\n {1, 2},\n};\n' + 'bool operator==(const A& lhs, const A& rhs);\nusing Alias = int;\n' + 'struct Point{\n int x = 0;\n};\n' + 'void f(){\n static int calls = 0;\n int local = 1;\n}')) + self.assertEqual([], self.errors('typedef struct{\n int x;\n} PABB_PACK pabb_Message;\n')) + + def test_using_directive_in_header(self): + self.assertFlags('TotW #153', wrap('using namespace Pokemon;'), HEADER) + self.assertEqual([], self.errors(wrap('using namespace Pokemon;'))) + self.assertEqual([], self.errors(wrap('inline void f(){\n using namespace std::chrono_literals;\n}'), + HEADER)) + + def test_forward_declarations(self): + source = wrap('class ImageViewRGB32;\nstruct Stats;\nclass Reader{\n friend class Tester;\n' + ' struct Stats;\n};') + self.assertEqual(2, sum('forward declaration' in m for m in self.errors(source, HEADER))) + self.assertEqual([], self.errors(source)) # .cpp files may declare local helpers + previous = wrap('') + changed = self.warnings(wrap('class ImageViewRGB32;'), HEADER, previous) + self.assertEqual(1, sum('forward declaration' in m for m in changed)) + self.assertEqual([], self.errors(wrap('class ImageViewRGB32;'), HEADER, previous)) + + def test_primary_template_before_its_specialization_is_not_a_forward_declaration(self): + self.assertClean(wrap('template \nclass MoveOnlyFunction;\n' + 'template \nclass MoveOnlyFunction{\n};')) + + def test_top_level_const_by_value_parameters_in_header_declarations(self): + self.assertFlags("'const int count'", wrap('void f(const int count, const std::string& name);'), HEADER) + self.assertFlags("'const size_t index = 0'", wrap('struct A{\n A(const size_t index = 0);\n};'), HEADER) + self.assertClean(wrap('void f(const std::string& a, const char* b, const std::vector c_ref,\n' + ' int d, std::function&& e);')) + self.assertEqual([], self.errors(wrap('inline void f(const int x){\n g(x);\n}'), HEADER)) + self.assertEqual([], self.errors(wrap('void f(const int count);'))) # .cpp declaration + + def test_bool_parameters(self): + self.assertFlags('a defaulted bool parameter', + wrap('void checkpoint_reattempt_loop(Env& env, bool save = true);'), HEADER) + self.assertFlags('2 bool parameters', + wrap('void exit_wild_battle(Context& c, bool stop_on_move_learn, bool prevent_evolution){\n}')) + self.assertClean(wrap('void f(Context& c, bool enabled);\nvoid g(Mode mode);\n' + 'struct A : B{\n virtual void h(bool a, bool b) override;\n};\n' + 'void call(){\n run(true, false);\n auto l = [](bool a, bool b){ return a; };\n}')) + + def test_existing_bool_signature_is_not_reported_when_its_line_changes(self): + previous = wrap('void f(bool a, bool b);') + self.assertEqual([], self.errors(wrap('void f(bool a, bool b); '), HEADER, previous)) + self.assertEqual(1, len(self.errors(wrap('void f(bool a, bool b, bool c);'), HEADER, previous))) + + +class CommentTests(StyleCase): + def test_comment_above_the_wrong_function_is_advisory(self): + source = wrap('// Save the game from the overworld with retries.\n' + '// Adds `text` to the overlay log, split at spaces.\n' + 'void add_wrapped_log(VideoOverlay& overlay, const std::string& text);\n' + 'bool save_game(Env& env);') + self.assertEqual([], self.errors(source, HEADER)) + warnings = self.warnings(source, HEADER) + self.assertEqual(1, len(warnings)) + self.assertIn('sits above add_wrapped_log but its first sentence describes save_game', warnings[0]) + + def test_comment_that_slid_onto_an_uncommented_neighbour_is_advisory(self): + source = wrap('uint16_t calorie_number() const;\n' + '// How many calorie number filters this detector uses.\n' + 'static void warm_ocr();') + self.assertEqual(1, len(self.warnings(source, HEADER))) + + def test_comment_on_a_commented_neighbour_mentioning_its_words_passes(self): + self.assertClean(wrap('// The last few screens, oldest first.\n' + 'std::string recent_screens() const;\n' + '// Throws with the recent screens appended.\n' + 'void fail(const std::string& message) const;'), HEADER) + + def test_comments_that_name_their_function_or_refer_to_others_pass(self): + self.assertClean(wrap( + '// Opens the save screen and reads the location (see `save_game()`).\n' + 'std::string read_location_from_save_screen(Context& c);\n' + 'bool save_game(Env& env);\n' + '// Remove all messages added by `add_log()`.\n' + 'void clear_log();\n' + 'void add_log(std::string message);')) + + +class AddedLinesTests(StyleCase): + def test_unchanged_legacy_lines_pass(self): + previous = in_function('if (x) return;\nstd::mutex m;') + current = in_function('if (x) return;\nstd::mutex m;\nrun();') + self.assertEqual([], self.errors(current, CPP, previous)) + self.assertEqual(1, len(self.errors(in_function('if (y) return;\nstd::mutex m;'), CPP, previous))) + + def test_crlf_and_findings_carry_lines(self): + findings = check(CPP, in_function('std::thread t(run);').replace('\n', '\r\n'), None)[0] + self.assertEqual([4], [f.line for f in findings]) + + +if __name__ == '__main__': + unittest.main()