Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions devtools/code_health/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 4 additions & 1 deletion devtools/code_health/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.')
Expand Down
20 changes: 18 additions & 2 deletions devtools/code_health/classes.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -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)]
Expand Down
Loading
Loading