From deffd78a73880fdaab74a7ead6d4f023537350e7 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sun, 15 Nov 2026 17:15:57 -0800 Subject: [PATCH] Code health: param_comment and test_only_api advisories; agent rules on vacuous tests param_comments.py reports uncommented literal arguments in calls of 3+ arguments; exposure.py reports public header names that only tests or their own .cpp use. Both advisory, with tags. autostory-code and reviewer get the three review rules from fork #590. --- .agents/agents/autostory-code.md | 7 + .agents/agents/reviewer.md | 6 + devtools/code_health/README.md | 19 +- devtools/code_health/__main__.py | 7 +- devtools/code_health/allow.py | 6 +- devtools/code_health/exposure.py | 118 ++++++++++++ devtools/code_health/param_comments.py | 174 ++++++++++++++++++ devtools/code_health/tests/test_exposure.py | 102 ++++++++++ .../code_health/tests/test_param_comments.py | 107 +++++++++++ 9 files changed, 540 insertions(+), 6 deletions(-) create mode 100644 devtools/code_health/exposure.py create mode 100644 devtools/code_health/param_comments.py create mode 100644 devtools/code_health/tests/test_exposure.py create mode 100644 devtools/code_health/tests/test_param_comments.py diff --git a/.agents/agents/autostory-code.md b/.agents/agents/autostory-code.md index 23443bbf25..b057d80034 100644 --- a/.agents/agents/autostory-code.md +++ b/.agents/agents/autostory-code.md @@ -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. diff --git a/.agents/agents/reviewer.md b/.agents/agents/reviewer.md index 26cd832ec0..f07bc55408 100644 --- a/.agents/agents/reviewer.md +++ b/.agents/agents/reviewer.md @@ -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: `; `## Verdict` sits on its own line, diff --git a/devtools/code_health/README.md b/devtools/code_health/README.md index ec3667c778..361fe606c4 100644 --- a/devtools/code_health/README.md +++ b/devtools/code_health/README.md @@ -95,14 +95,15 @@ void load_move_table(){ `// code-health: allow [,] -- ` 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. @@ -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 diff --git a/devtools/code_health/__main__.py b/devtools/code_health/__main__.py index ed19814e94..8c2ae31202 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 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 @@ -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: @@ -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) diff --git a/devtools/code_health/allow.py b/devtools/code_health/allow.py index 791ae9e3cc..baf5b93366 100644 --- a/devtools/code_health/allow.py +++ b/devtools/code_health/allow.py @@ -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 @@ -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) diff --git a/devtools/code_health/exposure.py b/devtools/code_health/exposure.py new file mode 100644 index 0000000000..5cd94810eb --- /dev/null +++ b/devtools/code_health/exposure.py @@ -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]])] diff --git a/devtools/code_health/param_comments.py b/devtools/code_health/param_comments.py new file mode 100644 index 0000000000..0f115dbbd9 --- /dev/null +++ b/devtools/code_health/param_comments.py @@ -0,0 +1,174 @@ +"""Parameter comments on literal arguments: `f(x, /*count=*/3, /*cool=*/0ms)`. + +In a call with three or more arguments, a bare literal says nothing about the parameter it +fills, so it needs a `/*param=*/` comment (Google "Function Arguments"; the user's review rule +on fork #590). Literals are numbers (with suffixes, so `0ms` and `1.5f`), `true`, `false`, +`nullptr` and brace lists of those (`{0, 0}`, `{}`). Only literals on added lines count. + +Not reported, because the call itself already names the values: +- string and character literals: a message, key or label reads as its own name; +- macros (ALL_CAPS callees) and `std::` functions: no parameter names / well-known signatures; +- format and log calls (callee name contains format, print or log, or the first argument is a + string literal): the format string's placeholders say what each argument is; +- a `nullptr` first argument: the repository's null logger or Qt parent slot + (`InternalProgramError(nullptr, PA_CURRENT_FUNCTION, message)`, `critical(nullptr, ...)`); +- value-type constructors (`ImageFloatBox`, `ImagePixelBox`, `Color`, a `*Point` or `*Rect`): + the type names the fields; +- a lone trailing duration in a call of at most four arguments + (`save_button_shows(console, context, 5s)`): the call's timeout or length, and the function + name says which. Longer calls (`ssf_press_button(context, buttons, delay, hold, 0ms)`) pass + several durations, so the slot is ambiguous and is still reported; +- calls whose arguments are all plain numbers: a box, color or point tuple whose type names + the fields (`ImageFloatBox(0.1, 0.2, 0.3, 0.4)`). +When the callee is declared in the same file with exactly one arity match, a comment that names +a different parameter is reported too. Lexical, like `style.py`: calls are only looked for inside +brace bodies, never in declarations. +""" +import bisect +import re + +from .findings import Finding +from .style import NOT_FUNCTIONS, added_lines, brace_kind, default_split, matching, rule, signature, \ + statements, strip_code + +MIN_ARGUMENTS = 3 +SHORT_CALL = 4 +CALL = re.compile(r'(?)\s*)*[A-Za-z_]\w*)\s*\(') +NUMBER = r"[-+]?\s*(?:0[xXbB][\da-fA-F']+|\d[\d']*\.?[\d']*(?:[eE][-+]?\d+)?|\.\d+)[A-Za-z_]*" +PLAIN_NUMBER = re.compile(r"[-+]?\s*(?:0[xX][\da-fA-F']+|\d[\d']*\.?[\d']*(?:[eE][-+]?\d+)?|\.\d+)[fFuUlL]*") +DURATION = re.compile(r"\d[\d']*(?:ms|s|min|h|us|ns)") +SCALAR = NUMBER + r'|true|false|nullptr' +LITERAL = re.compile(r'(?:' + SCALAR + r')|\{\s*(?:(?:' + SCALAR + r')(?:\s*,\s*(?:' + SCALAR + r'))*)?\s*\}') +STRING = re.compile(r'(?:(?:u8|u|U|L)?"[^"]*"\s*)+|\'[^\']*\'') +COMMENT = re.compile(r'/\*\s*([A-Za-z_]\w*)\s*=\s*\*/') +MACRO = re.compile(r'[A-Z][A-Z0-9_]*') +VALUE_TYPE = re.compile(r'\w*(?:Box|Color|Point|Rect)') +FORMAT_LIKE = re.compile(r'format|print|log', re.I) +CITE = ('Google "Function Arguments"', 'user review on fork #590') + + +def body_mask(code_text, parsed): + """Per offset of `code_text`, whether it lies inside a function body or a nested brace. + + `statements` emits one statement per `{`, in order, so the k-th `{` pairs with the k-th one.""" + opening = iter([brace_kind(s.text) for s in parsed if s.end == '{']) + mask, stack = bytearray(len(code_text)), [] + for offset, c in enumerate(code_text): + if c == '{': + stack.append(next(opening, 'other')) + elif c == '}' and stack: + stack.pop() + mask[offset] = 'other' in stack + return mask + + +def arguments(code_text, open_index, close_index): + """(start, end) offsets of each top-level argument between the parentheses.""" + spans, depth, start = [], 0, open_index + 1 + for k in range(open_index + 1, close_index): + c = code_text[k] + depth += (c in '([{') - (c in ')]}') + if c == ',' and depth == 0: + spans.append((start, k)) + start = k + 1 + if code_text[start:close_index].strip() or spans: + spans.append((start, close_index)) + return spans + + +def exempt(name, args): + """Whether the call names its values another way (see the module docstring).""" + short = re.split(r'::|\.|->', name.replace(' ', ''))[-1] + if short in NOT_FUNCTIONS or MACRO.fullmatch(short) or name.replace(' ', '').startswith('std::'): + return True + if VALUE_TYPE.fullmatch(short) or FORMAT_LIKE.search(short) or STRING.fullmatch(args[0]): + return True + literals = [arg for arg in args if LITERAL.fullmatch(arg)] + if len(args) <= SHORT_CALL and literals == [args[-1]] and DURATION.fullmatch(args[-1]): + return True + return all(PLAIN_NUMBER.fullmatch(arg) for arg in args) + + +def declared_parameters(parsed): + """{function name: [parameter names]} for names declared once per arity in this file.""" + found = {} + for statement in parsed: + sig = signature(statement) + if sig is None: + continue + names = [] + for param in sig.params: + last = re.search(r'([A-Za-z_]\w*)\s*(?:\[[^\]]*\])?$', default_split(param)[0]) + names.append(last.group(1) if last else '') + key = (sig.name.split('::')[-1], len(names)) + found.setdefault(key, set()).add(tuple(names)) + return {key: list(next(iter(v))) for key, v in found.items() if len(v) == 1} + + +def check(path, source, previous_source): + """Advisories for uncommented literal arguments on lines this change adds.""" + raw = source.replace('\r\n', '\n').replace('\r', '\n') + previous = None if previous_source is None else \ + previous_source.replace('\r\n', '\n').replace('\r', '\n').split('\n') + added = added_lines(raw.split('\n'), previous) + if not added: + return [] + code = strip_code(raw) + code_text = '\n'.join(code) + parsed = statements(code) + mask = body_mask(code_text, parsed) + params = declared_parameters(parsed) + line_of = line_index(code_text) + findings = [] + for match in CALL.finditer(code_text): + if not mask[match.start()]: + continue + open_index = match.end() - 1 + close_index = matching(code_text, open_index) + if close_index < 0: + continue + spans = arguments(code_text, open_index, close_index) + args = [code_text[a:b].strip() for a, b in spans] + if len(args) < MIN_ARGUMENTS or exempt(match.group(1), args): + continue + finding = call_finding(path, match.group(1), spans, (code_text, raw), line_of, added, params) + if finding: + findings.append(finding) + return findings + + +def call_finding(path, name, spans, texts, line_of, added, params): + """One finding per call: its uncommented literals, or comments naming the wrong parameter. + + `texts` is (blanked code, raw source); offsets match because blanking keeps columns.""" + code_text, raw = texts + short = re.split(r'::|\.|->', name.replace(' ', ''))[-1] + declared = params.get((short, len(spans))) + missing, wrong, line = [], [], None + for index, (start, end) in enumerate(spans): + arg = code_text[start:end].strip() + at = line_of(start + len(code_text[start:end]) - len(code_text[start:end].lstrip())) + if at not in added or (index == 0 and arg == 'nullptr'): + continue + comment = COMMENT.search(raw[start:end]) + if comment and declared and declared[index] and comment.group(1) != declared[index]: + wrong.append(f'/*{comment.group(1)}=*/ names parameter \'{declared[index]}\'') + line = line or at + elif not comment and LITERAL.fullmatch(arg): + missing.append(arg) + line = line or at + if not missing and not wrong: + return None + problems = [] + if missing: + plural = len(missing) > 1 + problems.append(f'literal argument{"s" if plural else ""} {", ".join(missing)} ' + f'need{"" if plural else "s"} a /*param=*/ comment') + problems += wrong + return Finding(path, line, rule(f'{short}(): {"; ".join(problems)}', *CITE), check='param_comment') + + +def line_index(text): + """A function from an offset in `text` to its 1-based line.""" + starts = [0] + [k + 1 for k, c in enumerate(text) if c == '\n'] + return lambda offset: bisect.bisect_right(starts, offset) diff --git a/devtools/code_health/tests/test_exposure.py b/devtools/code_health/tests/test_exposure.py new file mode 100644 index 0000000000..0868ac5c2e --- /dev/null +++ b/devtools/code_health/tests/test_exposure.py @@ -0,0 +1,102 @@ +import subprocess +import tempfile +import unittest +from pathlib import Path + +from devtools.code_health.exposure import check, git_users, test_file + + +DIR = 'SerialPrograms/Source/VideoGames/PokemonLZA/Programs/' +HEADER = DIR + 'PokemonLZA_BallThrow.h' +OWN_CPP = DIR + 'PokemonLZA_BallThrow.cpp' +TESTS = DIR + 'PokemonLZA_BallThrow_Tests.cpp' +CALLER = DIR + 'Farming/PokemonLZA_InPlaceCatcher.cpp' + + +def header(body): + return ('namespace PokemonAutomation{\nnamespace PokemonLZA{\n' + body + + '\n} // namespace PokemonLZA\n} // namespace PokemonAutomation\n') + + +# Fork #590 before its review: two helpers exposed next to the public throw_ball(). +BALL_THROW = header( + 'struct BallThrowOptions{\n int aim = 500;\n};\n' + 'struct BallScrolls{\n int count;\n};\n' + 'BallScrolls ball_scrolls(int right_scrolls);\n' + 'int throw_buttons_hold(const BallThrowOptions& options);\n' + 'void throw_ball(Context& context, const BallThrowOptions& options);\n' + 'void add_tests_BallThrow(UnitTestDatabase& database);') + + +def fake_users(table): + return lambda names: {name: set(table.get(name, ())) for name in names} + + +def names(findings): + return [f.message.split("'")[1] for f in findings] + + +class TestOnlyExposureTests(unittest.TestCase): + def test_flags_helpers_only_tests_or_their_own_cpp_use(self): + users = fake_users({ + 'BallThrowOptions': [HEADER, OWN_CPP, CALLER], + 'BallScrolls': [HEADER, OWN_CPP, TESTS], + 'ball_scrolls': [HEADER, OWN_CPP, TESTS], + 'throw_buttons_hold': [HEADER, OWN_CPP], + 'throw_ball': [HEADER, OWN_CPP, CALLER], + 'add_tests_BallThrow': [HEADER, OWN_CPP, DIR + '../PokemonLZA_Tests.cpp'], + }) + found = check(HEADER, BALL_THROW, None, users) + self.assertEqual(['BallScrolls', 'ball_scrolls', 'throw_buttons_hold'], names(found)) + self.assertIn('public only for PokemonLZA_BallThrow_Tests.cpp', found[1].message) + self.assertIn('used only in its own .cpp', found[2].message) + self.assertEqual({'test_only_api'}, {f.check for f in found}) + + def test_names_without_users_or_used_by_other_public_declarations_pass(self): + # A type in a kept function's signature is part of its API; a name nothing uses yet + # is new API for a later caller. + users = fake_users({ + 'BallThrowOptions': [HEADER, OWN_CPP, TESTS], + 'BallScrolls': [HEADER, OWN_CPP, TESTS], + 'ball_scrolls': [HEADER, OWN_CPP, CALLER], + 'throw_ball': [HEADER, OWN_CPP, CALLER], + }) + self.assertEqual([], check(HEADER, BALL_THROW, None, users)) + + def test_only_names_new_since_the_base_count(self): + users = fake_users({'ball_scrolls': [HEADER, OWN_CPP, TESTS], 'BallScrolls': [HEADER, OWN_CPP]}) + self.assertEqual([], check(HEADER, BALL_THROW, BALL_THROW, users)) + + def test_sources_and_test_headers_are_not_checked(self): + users = fake_users({'ball_scrolls': [OWN_CPP, TESTS]}) + self.assertEqual([], check(OWN_CPP, BALL_THROW, None, users)) + self.assertEqual([], check(DIR + 'PokemonLZA_BallThrow_Tests.h', BALL_THROW, None, users)) + + def test_test_files(self): + for path, expected in ((TESTS, True), (DIR + 'Foo_Test.cpp', True), + ('SerialPrograms/Source/Tests/CommandLineTests.cpp', True), + (OWN_CPP, False), (DIR + 'SpeedTest.cpp', False)): + with self.subTest(path=path): + self.assertEqual(expected, test_file(path)) + + +class GitUsersTests(unittest.TestCase): + def test_one_grep_maps_each_name_to_the_files_that_mention_it_as_a_word(self): + with tempfile.TemporaryDirectory() as temp: + root = Path(temp) + for path, text in (('Common/a.h', 'int helper();\nint helper_two();\n'), + ('Common/a_Tests.cpp', 'int x = helper();\n'), + ('Common/b.cpp', 'int y = helper_two();\n'), + ('Common/notes.txt', 'helper\n')): + (root / path).parent.mkdir(parents=True, exist_ok=True) + (root / path).write_text(text) + subprocess.check_call(['git', '-C', temp, 'init', '-q']) + subprocess.check_call(['git', '-C', temp, 'add', '.']) + found = git_users(root)(['helper', 'helper_two', 'absent']) + self.assertEqual({'helper': {'Common/a.h', 'Common/a_Tests.cpp'}, + 'helper_two': {'Common/a.h', 'Common/b.cpp'}, + 'absent': set()}, found) + + +if __name__ == '__main__': + unittest.main() diff --git a/devtools/code_health/tests/test_param_comments.py b/devtools/code_health/tests/test_param_comments.py new file mode 100644 index 0000000000..d78beca90f --- /dev/null +++ b/devtools/code_health/tests/test_param_comments.py @@ -0,0 +1,107 @@ +import unittest + +from devtools.code_health import allow +from devtools.code_health.param_comments import check + + +CPP = 'SerialPrograms/Source/VideoGames/PokemonLZA/Programs/Example.cpp' + + +def in_function(body): + return ('namespace PokemonAutomation{\n' + 'void example(ProControllerContext& context){\n' + body + '\n}\n' + '} // namespace PokemonAutomation\n') + + +def messages(source, previous=None): + return [f.message for f in check(CPP, source, previous)] + + +class LiteralArgumentTests(unittest.TestCase): + def test_flags_uncommented_literals_in_long_calls(self): + # The two calls fork #590's review asked to comment, and #572's middle literal. + for line, literal in ( + ('pbf_controller_state(context, BUTTON_ZL, DPAD_NONE, {0, 0}, {0, 0}, lock_on);', '{0, 0}, {0, 0}'), + ('ssf_press_button(context, BUTTON_ZL | BUTTON_ZR, aim, hold, 0ms);', '0ms'), + ('auto db = make_story_select_database(story_list(), 2, story_list().size());', '2'), + ('pbf_press_button(context, BUTTON_A, 160ms, 400ms);', '160ms, 400ms'), + ('sign_room_walk(Direction::EAST, 2, {3, 3}, true);', '2, {3, 3}, true'), + ('reader.read(image, nullptr, -1.5f);', 'nullptr, -1.5f'), + ('run(context, {}, options);', '{}')): + with self.subTest(line=line): + found = messages(in_function(line)) + self.assertEqual(1, len(found), found) + self.assertIn(f' {literal} need', found[0]) + + def test_commented_literals_pass(self): + source = in_function( + 'pbf_controller_state(\n' + ' context, BUTTON_ZL, DPAD_NONE,\n' + ' /*left_joystick=*/{0, 0}, /*right_joystick=*/{0, 0},\n' + ' /*duration=*/lock_on\n' + ');\n' + 'ssf_press_button(context, BUTTONS, /*delay=*/aim, /*hold=*/hold, /*cool=*/0ms);') + self.assertEqual([], messages(source)) + + def test_exemptions(self): + for line in ( + 'f(a, b);', # fewer than three arguments + 'f(a, b, c);', # no literal + 'save_button_shows(console, context, 5s);', # lone trailing duration + 'env.log(std::format("{} {}", 1, 2), COLOR_RED, true);', # log call + 'std::string s = std::format("{} of {}", index, 3);', # format call + 'report( "story {} failed", 3, true);', # format string first + 'auto x = std::clamp(value, 0, 255);', # std:: signature + 'PA_CHECK(value, 3, true);', # macro + 'throw InternalProgramError(nullptr, PA_CURRENT_FUNCTION, "bad row");', + 'ImageFloatBox box(0.1, 0.2, 0.3, 0.4);', # value tuple + 'return ImageFloatBox(left + 0.1 * i, top, 0.015, 0.2);', # value type + 'box.critical(nullptr, "Error", text);', # null Qt parent + 'select(image, "label", "other", name);', # strings name themselves + 'if (a(1) && b(2) && c(3)){\n go();\n}'): # three one-argument calls + with self.subTest(line=line): + self.assertEqual([], messages(in_function(line))) + + def test_long_call_lone_duration_is_reported(self): + self.assertEqual(1, len(messages(in_function('wait(console, context, BUTTON_A, timeout, 0ms);')))) + + def test_leading_nullptr_is_exempt_but_not_the_rest(self): + found = messages(in_function('execute(nullptr, false, 2000ms);')) + self.assertEqual(1, len(found), found) + self.assertIn(' false, 2000ms need', found[0]) + + def test_declarations_and_namespace_scope_are_not_calls(self): + source = ('namespace PokemonAutomation{\n' + 'void walk(int tiles, bool run = true, Milliseconds wait = 0ms, int retries = 3);\n' + 'const ImageFloatBox BOX(0.1, 0.2, 0.3, 0.4);\n' + '} // namespace PokemonAutomation\n') + self.assertEqual([], messages(source)) + + def test_only_added_lines_count(self): + old = in_function('pbf_press_button(context, BUTTON_A, 160ms, 400ms);') + new = in_function('pbf_press_button(context, BUTTON_A, 160ms, 400ms);\nok();') + self.assertEqual([], messages(new, old)) + self.assertEqual(1, len(messages(new))) + + def test_comment_must_name_the_parameter_declared_in_this_file(self): + source = ('namespace PokemonAutomation{\n' + 'void walk(int tiles, bool run, int retries){\n}\n' + 'void example(){\n' + ' walk(/*tiles=*/2, /*running=*/true, /*retries=*/3);\n' + '}\n' + '} // namespace PokemonAutomation\n') + found = messages(source) + self.assertEqual(1, len(found), found) + self.assertIn("/*running=*/ names parameter 'run'", found[0]) + + def test_finding_carries_its_tag_check(self): + source = in_function(' // code-health: allow param_comment -- the controller state reads as a table of joystick axes\n' + ' pbf_controller_state(context, BUTTON_ZL, DPAD_NONE, {0, 0}, {0, 0}, lock_on);') + findings = check(CPP, source, None) + allowances, errors = allow.parse(CPP, source) + kept, waived, unattached = allow.waive(CPP, source, allowances, findings) + self.assertEqual(([], 1, [], []), (kept, len(waived), unattached, errors)) + + +if __name__ == '__main__': + unittest.main()