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
7 changes: 7 additions & 0 deletions .agents/agents/autostory-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,13 @@ being restated.
expectation, the name not inside the input; `std::string_view` by value for read-only string
params; `std::optional`, not sentinels like `""` or `-1`; pixel readers in `Detectors/` read only
and press nothing, presses go in `Actions/`.
- No vacuous tests: a test that only restates the code's arithmetic or constants, or passes for
any implementation, is not added. Test behavior a caller relies on.
- Don't widen a header to test internals: test through the public function, or keep the helper
in the .cpp's anonymous namespace (code health `test_only_api`).
- A literal argument in a call of 3+ arguments gets a parameter comment:
`pbf_press_button(context, BUTTON_A, /*hold=*/160ms, /*release=*/400ms)` (code health
`param_comment`).
- **Commit early, finish in one turn.** Commit and push as soon as the scoped checks pass; CI runs the
full build and tests after the push. Then, in the foreground and without ending the turn:
verify → commit → push → open the PR → confirm the PR's file list. Never end with an unpushed commit.
Expand Down
6 changes: 6 additions & 0 deletions .agents/agents/reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,12 @@ being restated.
name not inside the input; `std::string_view` by value for read-only string params;
`std::optional`, not sentinels like `""` or `-1`; pixel readers in `Detectors/` read only and
press nothing, presses go in `Actions/`; new code in its final file and module; line endings kept.
Flag vacuous tests (they only restate the code's arithmetic or constants, or pass for any
implementation): ask for a test of behavior a caller relies on, or none. Flag a header widened
to test internals: test through the public function, or keep the helper in the .cpp's anonymous
namespace. Flag literal arguments without a parameter comment in calls of 3+ arguments
(`/*hold=*/160ms`). Code health reports the last two as `test_only_api` and `param_comment`
advisories; read them, they don't fail CI.
- **Time limit.** At the wall-clock limit, post the findings so far with verdict `NEEDS_REWORK`,
say the review is partial, and report.
- **Review delivery.** Line 1 is `Reviewed SHA: <full sha>`; `## Verdict` sits on its own line,
Expand Down
19 changes: 16 additions & 3 deletions devtools/code_health/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,14 +95,15 @@ void load_move_table(){
`// code-health: allow <check>[,<check>] -- <justification>` lets the listed metrics of one
function or class exceed their limit. Checks are the metric names in the table above:
`file_lines`, `function_lines`, `nesting`, `parameters`, `public_methods`, `public_data`,
`single_method_interface`, `header_symbols`. Four style findings take a tag too: `char_pointer`,
`overload_prefix`, `out_param_order` and `string_concat`, for a C API or a fixed interface that needs them. Other style and layering
`single_method_interface`, `header_symbols`. Six style findings take a tag too: `char_pointer`,
`overload_prefix`, `out_param_order`, `string_concat`, `param_comment` and `test_only_api`, for a C API
or a fixed interface that needs them. Other style and layering
findings have no bypass.

- **Place it** on the function's or class's first line, or in the comment block directly above
it (only `//` comment and `template` lines between). A `file_lines` tag goes in the first 20
lines of the file, and so does a `header_symbols` tag. A style tag (`char_pointer`, `overload_prefix`,
`out_param_order`, `string_concat`) goes on the flagged line or in the comment block directly above it, and waives the finding whether it is an error or advisory. A tag that attaches to nothing fails.
`out_param_order`, `string_concat`, `param_comment`, `test_only_api`) goes on the flagged line or in the comment block directly above it, and waives the finding whether it is an error or advisory. A tag that attaches to nothing fails.
- **Justify it:** the text after `--`, on the tag line itself, must be at least 40 characters and 6 words,
and say why splitting would make the code worse. Unknown checks, a missing or short
justification, or a malformed tag fail.
Expand Down Expand Up @@ -157,9 +158,21 @@ lexer, not a parser: rules that need types stay in review.
| Output parameters last: a non-const `T&` parameter before a by-value, `const&` or `&&` one. Not reported: context handles conventionally first (`*Env`/`*Environment`, `*Context`, `*Actions`, `*Backend`, `*Option`, `*Logger`, `ConsoleHandle`, `VideoStream`, `VideoOverlay`, `VideoFeed`, `AudioFeed`, `CancellableScope`, `UnitTestDatabase`, `AsyncCommandSession`, `std::*stream`); pointers, packs and function types (neither input nor output); constructors, operators, `override`/`final`, `= delete`; out-of-class `A::f` definitions in a `.cpp` (the header declaration is checked); a changed line whose signature keeps its parameter kinds | advisory for now, error before upstream (tag: `out_param_order`) | Google "Function Parameter Ordering" |
| Building a string with `+`: a string literal, `std::to_string(...)` or `std::string(...)` next to a binary `+` (also `s += "a" + b`). Not reported: `+=` appends, `++`, numeric/pointer `+`, files including Qt headers (QString) | advisory for now, error before upstream (tag: `string_concat`) | fork AGENTS.md "Strings": use `std::format` |
| A comment whose first sentence describes the neighbouring function, none of its own | advisory | CONTRIBUTING; Google "Function Comments" |
| A literal argument without a `/*param=*/` comment in a call of 3+ arguments: numbers (`2`, `0ms`, `1.5f`), `true`/`false`, `nullptr`, brace lists of those (`{0, 0}`, `{}`). With the callee declared once per arity in the same file, a comment naming another parameter too. Not reported: string/char literals, macros, `std::` calls, format/log calls (name contains format/print/log, or a string literal first), all-number tuples and `*Box`/`*Color`/`*Point`/`*Rect` constructors, a leading `nullptr` (null logger or Qt parent), a lone trailing duration in a call of at most 4 arguments (`save_button_shows(console, context, 5s)`); calls outside brace bodies (declarations, default arguments) (`param_comments.py`) | advisory (tag: `param_comment`) | Google "Function Arguments"; user review on fork #590 |
| A public namespace-scope name a header adds (on an added line, new since the base) whose only users outside the header and its own .cpp are test files (`*_Tests.cpp`, `*_Test.cpp`, `Tests/`), or that only its own .cpp uses. Users: one `git grep -o -w` over tracked C++. Not reported: names nothing uses yet, names another kept public declaration of the header mentions (parameter, return or member type), `add_tests*` hooks, test headers (`exposure.py`) | advisory (tag: `test_only_api`) | user review on fork #590: test through the public function, or keep the helper in the .cpp's anonymous namespace |

Advisories print as `Advisory:` lines and `::warning` annotations and never fail.

`param_comment` and `test_only_api` are advisory by their measured rates (2026-11-15). On 18 fork
PRs (#567-#591) `param_comment` reported 379 calls, 257 of them in test files and 91 controller
timings (`pbf_press_button(context, BUTTON_A, 160ms, 400ms)`); no lexer misreads in a 42-finding
sample, and it reports exactly the review's sites on #590 (`{0, 0}`, `0ms`) and #572 (`2`). As a
failure it would fail nearly every open program PR. `test_only_api` reported 203 names on 10 of
those PRs and exactly #590's three helpers; on the PLZA slice stack 31 of 64 names gained a
non-test caller later in the stack (API added one PR before its caller), and upstream's
`Common/ControllerStates` C-style headers (constants and `*_equals` used only by their own .cpp)
are reported too.

## Build and native C++ tests in one command

The existing `.github/workflows/cpp-ci-serial-programs-base.yml` already runs
Expand Down
7 changes: 6 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 allow, header_api, layering, style
from . import allow, exposure, header_api, layering, param_comments, style
from .classes import measure_classes
from .findings import annotations
from .git_files import changed_files, default_base, read_revision
Expand All @@ -22,6 +22,7 @@ def run(root, base_ref=None, github=False):
base_ref, how = default_base(root)
print(f'Base: {base_ref} ({how}).')
changes = changed_files(root, base_ref)
users = exposure.git_users(root)
failures, notes, bypassed = [], [], []
advisory = 0
for current, original in changes:
Expand All @@ -40,6 +41,10 @@ def run(root, base_ref=None, github=False):
notes.extend(unneeded)
style_errors, style_notes = style.check(current, source, previous_source)
style_errors += header_api.prefix_overloads(current, source, previous_source)
# Advisory: both report many sites a reviewer may accept (pbf_* timings, API for a
# later PR in a stack); see the README's Style table for the measured rates.
style_notes += param_comments.check(current, source, previous_source)
style_notes += exposure.check(current, source, previous_source, users)
# Waive errors and advisories in one pass, so a tag on either counts as used.
kept, waived, unattached = allow.waive(current, source, allowances, style_errors + style_notes)
failures.extend([f for f in kept if f in style_errors] + unattached)
Expand Down
6 changes: 4 additions & 2 deletions devtools/code_health/allow.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
A tag on a function's or class's first line, or in the comment block directly above it, lets
that function's or class's listed metrics exceed their limit up to a hard ceiling. A
`file_lines` or `header_symbols` tag goes in the first FILE_TAG_LINES lines. A STYLE_CHECKS tag
(`char_pointer`, `overload_prefix`, `out_param_order`, `string_concat`) waives that style finding
(`char_pointer`, `overload_prefix`, `out_param_order`, `string_concat`, `param_comment`,
`test_only_api`) waives that style finding
on its own line or the line below its comment block. Every bypass is printed, quoting its
justification, so reviewers see it; malformed, unknown or misplaced tags fail."""
import re
Expand All @@ -13,7 +14,8 @@
from .findings import Finding

# Style findings a tag can bypass; they attach like a function's tag, to the finding's line.
STYLE_CHECKS = ('char_pointer', 'overload_prefix', 'out_param_order', 'string_concat')
STYLE_CHECKS = ('char_pointer', 'overload_prefix', 'out_param_order', 'string_concat', 'param_comment',
'test_only_api')
# File-level metrics: the tag goes in the first FILE_TAG_LINES lines.
FILE_CHECKS = ('file_lines',) + tuple(HEADER_LIMITS)
CHECKS = (('file_lines', 'function_lines', 'nesting', 'parameters') + tuple(CLASS_LIMITS)
Expand Down
118 changes: 118 additions & 0 deletions devtools/code_health/exposure.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
"""Test-only header exposure: a public name a header adds whose only users are tests.

A helper moved into a header so a `*_Tests.cpp` can call it widens the API for the tests'
sake (user review on fork #590). Test through the public function, or keep the helper in
the .cpp's anonymous namespace. Names are the header's public namespace-scope names
(`header_api.public_names`); only names new since the base revision, on added lines, count.
Users are the tracked C++ files that mention the name as a word (`git grep -w`), other than
the header itself and its own .cpp. Reported: a new name that only test files use, or that
only its own .cpp uses (tests in the same .cpp need no header declaration). A name with no
users at all is new API for a caller still to come, and a name that another public declaration
of the header mentions (a parameter, return or member type) is part of that API: neither is
reported.

Not reported: test headers (`*_Tests.h`, `Tests/`) and test registration hooks
(`add_tests*`), which exist to be called by the test runner.
"""
import re
import subprocess
from pathlib import PurePosixPath

from .findings import Finding
from .git_files import EXTENSIONS
from .header_api import declared_name, normalize, public, public_names
from .style import HEADERS, added_lines, rule, scopes, statements, strip_code

REGISTRATION = re.compile(r'add_tests\w*')
CITE = 'user review on fork #590'


def test_file(path):
"""`*_Tests.cpp`, `*_Test.cpp` and `*_Tests.h` files and anything under a `Tests/` directory."""
pure = PurePosixPath(path)
return 'Tests' in pure.parts[:-1] or re.search(r'_Tests?$', pure.stem) is not None


def git_users(root):
"""A function from names to {name: tracked first-party C++ files that mention it as a word}.

One `git grep -o` for all names: a name per call would take minutes on a large change."""
pathspecs = [f'{top}/*{ext}' for top in ('Common', 'SerialPrograms') for ext in sorted(EXTENSIONS)]

def users(names):
found = {name: set() for name in names}
if not names:
return found
patterns = [arg for name in sorted(names) for arg in ('-e', name)]
result = subprocess.run(['git', '-C', str(root), 'grep', '-o', '-w', '-F', '-I', '--null',
*patterns, '--', *pathspecs], capture_output=True, text=True)
if result.returncode not in (0, 1):
raise ValueError(f'git grep for header names failed: {result.stderr.strip()}')
for line in result.stdout.splitlines():
path, _, match = line.partition('\0')
if match in found and '3rdParty' not in path:
found[match].add(path)
return found
return users


def own_files(path):
"""The header and the sources that implement it: same directory and stem."""
stem = str(PurePosixPath(path).with_suffix(''))
return {stem + ext for ext in EXTENSIONS}


def mentions_by_owner(source):
"""{public name: identifiers its declaration mentions}, members of a public class included."""
owners = {}
for statement, enclosing in scopes(statements(strip_code(normalize(source)))):
if statement.end == '}':
continue
if statement.namespace_scope and public(enclosing):
owner = declared_name(statement)
else:
outer = [name for kind, name in enclosing if kind == 'class']
owner = outer[0] if outer and public([f for f in enclosing if f[0] != 'class']) else None
if owner:
owners.setdefault(owner, set()).update(re.findall(r'[A-Za-z_]\w*', statement.text))
return owners


def exposure(path, mentions):
"""Why a name that `mentions` (files) use is exposed only for tests or its own .cpp, or None."""
outside = sorted(mentions - own_files(path))
if any(not test_file(user) for user in outside):
return None
if outside:
return f"public only for {', '.join(PurePosixPath(u).name for u in outside)}"
if mentions & (own_files(path) - {path}):
return 'used only in its own .cpp'
return None


def check(path, source, previous_source, users):
"""Advisories for public names this header adds that only tests or its own .cpp use.

`users(names)` returns {name: repository files that mention it} (see `git_users`)."""
if not path.endswith(HEADERS) or test_file(path):
return []
previous = set(public_names(previous_source)) if previous_source is not None else set()
added = added_lines(normalize(source).split('\n'),
None if previous_source is None else normalize(previous_source).split('\n'))
names = public_names(source)
new = [name for name, line in names.items()
if name not in previous and line in added and not REGISTRATION.fullmatch(name)]
mentions = users(new) if new else {}
exposed = {name: why for name in new for why in [exposure(path, mentions.get(name, set()))] if why}
owners = mentions_by_owner(source)
changed = True
while changed: # a name that a kept public declaration mentions is part of its API
needed = {name for name in exposed for owner, words in owners.items()
if owner != name and owner not in exposed and name in words}
changed = bool(needed)
for name in needed:
del exposed[name]
return [Finding(path, names[name], rule(
f"'{name}' is {why}; test through the public function, or keep it in the .cpp's "
'anonymous namespace (ignore if a later PR in the stack calls it)', CITE), check='test_only_api')
for name, why in sorted(exposed.items(), key=lambda item: names[item[0]])]
Loading
Loading