|
| 1 | +#!/usr/bin/env python3 |
| 2 | +# SPDX-FileCopyrightText: Copyright (c) 2026 Northeastern University |
| 3 | +# SPDX-License-Identifier: Apache-2.0 |
| 4 | +"""Fail when Doxygen reports a warning in a file the pull request changes. |
| 5 | +
|
| 6 | + check_docs_warnings.py LOG FRAGMENT [--base SHA --head SHA] |
| 7 | +
|
| 8 | +The `docs` CMake target exits 0 whatever Doxygen printed, so the log is the only |
| 9 | +place the warnings show up. With --base and --head the check is a partial scan: |
| 10 | +only warnings in the files that `git diff base..head` lists fail it, and the |
| 11 | +rest are reported as information, so a gap in a file the pull request does not |
| 12 | +touch cannot block it. Without them every warning counts. |
| 13 | +
|
| 14 | +Doxygen gives some warnings (a function whose parameters are not all documented) |
| 15 | +no file, only the member name in `<name>`. Those count when a changed C or C++ |
| 16 | +file declares or defines that member. |
| 17 | +
|
| 18 | +On a failure the whole log goes to the job output and a short summary to the |
| 19 | +report fragment, which the CI report folds into its one comment per pull |
| 20 | +request. The summary stays small on purpose: a comment holds about 65000 |
| 21 | +characters and a strict run reports over a thousand warnings. |
| 22 | +""" |
| 23 | +import argparse |
| 24 | +import collections |
| 25 | +import os |
| 26 | +import re |
| 27 | +import subprocess |
| 28 | +import sys |
| 29 | + |
| 30 | +SHOWN_FILES = 25 |
| 31 | +SHOWN_WARNINGS = 20 |
| 32 | +LOCATED = re.compile(r"^(?P<path>[^\s:]+):(?P<line>\d+): warning: (?P<msg>.*)$") |
| 33 | +MEMBER = re.compile(r"member (\S+) are not documented") |
| 34 | +SOURCES = (".h", ".hpp", ".c", ".cpp", ".i") |
| 35 | +NOT_A_TYPE = r"(?!(?:return|else|case|delete|new|throw|goto)\b)" |
| 36 | + |
| 37 | + |
| 38 | +def changed_files(base, head): |
| 39 | + out = subprocess.run(["git", "diff", "--name-only", "--diff-filter=ACMR", f"{base}..{head}"], |
| 40 | + capture_output=True, text=True, check=True).stdout |
| 41 | + return {line for line in out.splitlines() if line} |
| 42 | + |
| 43 | + |
| 44 | +def changed_sources(files): |
| 45 | + texts = [] |
| 46 | + for path in sorted(f for f in files if f.endswith(SOURCES)): |
| 47 | + try: |
| 48 | + with open(path, encoding="utf-8", errors="ignore") as handle: |
| 49 | + texts.append(handle.read()) |
| 50 | + except OSError: |
| 51 | + continue |
| 52 | + return texts |
| 53 | + |
| 54 | + |
| 55 | +def owns(texts, qualified): |
| 56 | + """True when a changed C or C++ file declares or defines the member `qualified`. |
| 57 | +
|
| 58 | + A page of documentation that names the function, or a call to it, does not |
| 59 | + make it one of the pull request's own members, so only declarations count: the |
| 60 | + type that owns it, a definition `Owner::name(`, or for a plain function a line |
| 61 | + that starts with a return type and then the name.""" |
| 62 | + parts = [part for part in qualified.split("::") if part] |
| 63 | + name = parts[-1] |
| 64 | + owner = parts[-2] if len(parts) > 1 else None |
| 65 | + patterns = [] |
| 66 | + if owner: |
| 67 | + patterns.append(r"\b(?:class|struct)\s+%s\b" % re.escape(owner)) |
| 68 | + patterns.append(r"\b%s::%s\s*\(" % (re.escape(owner), re.escape(name))) |
| 69 | + else: |
| 70 | + patterns.append(r"(?m)^[ \t]*%s(?:[\w:<>*&]+[ \t]+)+[*&]*%s\s*\(" % (NOT_A_TYPE, re.escape(name))) |
| 71 | + return any(re.search(pattern, text) for pattern in patterns for text in texts) |
| 72 | + |
| 73 | + |
| 74 | +def main(): |
| 75 | + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) |
| 76 | + parser.add_argument("log") |
| 77 | + parser.add_argument("fragment") |
| 78 | + parser.add_argument("--base") |
| 79 | + parser.add_argument("--head") |
| 80 | + args = parser.parse_args() |
| 81 | + |
| 82 | + if not os.path.isfile(args.log): |
| 83 | + print(f"::error::Doxygen wrote no warning log at {args.log}, so the build did not run") |
| 84 | + return 1 |
| 85 | + with open(args.log, encoding="utf-8", errors="replace") as handle: |
| 86 | + raw = handle.read() |
| 87 | + lines = [line for line in raw.splitlines() if "warning:" in line] |
| 88 | + root = os.getcwd() + "/" |
| 89 | + |
| 90 | + scope = None |
| 91 | + if args.base and args.head: |
| 92 | + try: |
| 93 | + scope = changed_files(args.base, args.head) |
| 94 | + except (subprocess.CalledProcessError, OSError) as exc: |
| 95 | + print(f"::warning::cannot list the changed files ({exc}); scanning the whole tree") |
| 96 | + |
| 97 | + sources = changed_sources(scope) if scope is not None else [] |
| 98 | + counted, elsewhere = [], [] |
| 99 | + for line in lines: |
| 100 | + text = line.replace(root, "") |
| 101 | + match = LOCATED.match(text) |
| 102 | + if scope is None: |
| 103 | + counted.append((match.group("path") if match else None, text)) |
| 104 | + elif match and not match.group("path").startswith("<"): |
| 105 | + (counted if match.group("path") in scope else elsewhere).append((match.group("path"), text)) |
| 106 | + else: |
| 107 | + member = MEMBER.search(text) |
| 108 | + owned = member is None or owns(sources, member.group(1)) |
| 109 | + (counted if owned else elsewhere).append((None, text)) |
| 110 | + |
| 111 | + mode = "the files this pull request changes" if scope is not None else "the whole tree" |
| 112 | + if raw.strip(): |
| 113 | + print(raw.rstrip("\n")) |
| 114 | + if not counted and not elsewhere: |
| 115 | + print("Doxygen reported no warnings.") |
| 116 | + return 0 |
| 117 | + |
| 118 | + per_file = collections.Counter(path for path, _ in counted if path) |
| 119 | + unplaced = sum(1 for path, _ in counted if not path) |
| 120 | + total, fails = len(lines), len(counted) |
| 121 | + lead = (f"{fails} warning(s) in {mode}, which fail the check; {len(elsewhere)} more elsewhere, which do not." |
| 122 | + if scope is not None else f"{fails} warning(s) in {mode}, which fail the check.") |
| 123 | + fragment = ["### Doxygen warnings", "", lead + " The full list is in the job log and the `doxygen-warnings` artifact of the `Docs` workflow.", ""] |
| 124 | + if fails: |
| 125 | + fragment += ["| Warnings | File |", "|---:|---|"] |
| 126 | + for path, count in per_file.most_common(SHOWN_FILES): |
| 127 | + fragment.append(f"| {count} | `{path}` |") |
| 128 | + if unplaced: |
| 129 | + fragment.append(f"| {unplaced} | (no file, a member of a changed file) |") |
| 130 | + if len(per_file) > SHOWN_FILES: |
| 131 | + fragment += ["", f"…and {len(per_file) - SHOWN_FILES} more file(s)."] |
| 132 | + fragment += ["", f"First {min(SHOWN_WARNINGS, fails)}:", "", "```"] |
| 133 | + fragment += [text[:220] for _, text in counted[:SHOWN_WARNINGS]] |
| 134 | + fragment.append("```") |
| 135 | + else: |
| 136 | + elsewhere_files = collections.Counter(path for path, _ in elsewhere if path) |
| 137 | + fragment += ["Gaps in files this pull request does not change, by file:", "", "| Warnings | File |", "|---:|---|"] |
| 138 | + for path, count in elsewhere_files.most_common(10): |
| 139 | + fragment.append(f"| {count} | `{path}` |") |
| 140 | + with open(args.fragment, "w", encoding="utf-8") as handle: |
| 141 | + handle.write("\n".join(fragment) + "\n") |
| 142 | + |
| 143 | + print(f"{fails} of {total} warning(s) are in {mode}.") |
| 144 | + if fails: |
| 145 | + print(f"::error::Doxygen reported {fails} warning(s) in {mode}; the full list is above and in the doxygen-warnings artifact") |
| 146 | + return 1 |
| 147 | + return 0 |
| 148 | + |
| 149 | + |
| 150 | +if __name__ == "__main__": |
| 151 | + sys.exit(main()) |
0 commit comments