Baseline and suppressions

Baseline #

agentica cchecker.agc -p build --baseline cchecker-baseline.json --update-baseline   # writes the file, exit 0
agentica cchecker.agc -p build --baseline cchecker-baseline.json                     # fails on new findings only

A finding matches the baseline by its code, its file and its message, never its line. The file holds a count for each kind, so a second finding of a kind the baseline holds once is new. The file is read before any tool runs, and written in one rename.

A run covers the tools and the files whose job ended well. Only a full run (every file of a database, with no --exclude, no FILE subset, no skipped file and no failed job) covers the headers and the files that left the database. fixed counts the accepted findings of that scope that no tool found this time, and --update-baseline replaces the entries of that scope and keeps the others, so --tools gcc or a subset of FILEs updates only what it ran. A header that the run did not name keeps the larger count of its entry (other flags can show other findings in it); only a full run lowers it.

--update-baseline refuses to write, exits 2 and leaves the file as it was when a tool failed, when the database has a file that was skipped (outside the working directory), with --checks (a baseline made with other checks would lose the findings of the default ones), and, when the rules run, with --no-infer, a [library] flag other than short_lock_sections set to false, or a file of -c that leaves out a name of short or hot of the project's [roots] (only [roots] is compared, not follow_cold or [assume]).

A baseline entry whose finding is gone is stale: a new finding of the same code, file and message would match it later and be accepted unseen. A run names each stale entry of its scope (the entries that fixed counts and --update-baseline drops): one line each after the summary, and stale in --json, with the count that was not found again. With --strict-baseline they make the run exit 1 (and clean false); an entry outside the scope never fails the run. --strict-baseline needs --baseline and the default --checks (fewer checks make the entries of the others look stale), and does not go with --update-baseline. With a check of the rules off (--no-infer, a [library] flag other than short_lock_sections set to false, a file of -c that leaves out the project's [roots]), the stale entries of the rules do not fail the run, with a warning on standard error; those of the other tools still do.

Versions of the tools #

The findings of gcc -fanalyzer and clang-tidy change with the version of the tool. An --update-baseline of every file (no FILE and no --exclude) writes the first line of --version of each tool it ran into tools of the file (gcc, clang-tidy, and clang for the rules):

{"version": 1, "tools": {"clang":"Debian clang version 19.1.7 (3+b1)","clang-tidy":"Debian LLVM version 19.1.7","gcc":"gcc (Debian 14.2.0-19) 14.2.0"}, "findings": [...]}

A run with a tool of another version prints a warning on standard error, before the summary, that names both lines; version_changes of --json lists them. Versions are compared by their number (14.2.0), so another build of the same version (Debian and Ubuntu) is no change. It is not an error: the counts decide the exit code. When the run also has stale entries, the warning says they may come from the change: write the baseline again with the tools of the project (the ones CI uses) before you trust --strict-baseline.

Only the tools that the run ran are compared, and a tool that prints no version is not. A version is written only by an update of every file (--tools gcc counts as every file of gcc; FILEs and --exclude do not): a partial update keeps the stored versions. After an update of every file, a tool that ran and printed no version loses its stored one (the update says so on standard error), and a tool that did not run keeps it. A baseline with no tools reads with no warning, and the next update of every file adds them. The format is stable across versions: the file stays "version": 1, and an older cchecker reads a file with tools and ignores them.

Suppressions #

A finding that is a false positive is suppressed next to the code, with the reason. A comment that trails code holds for the findings of its line; a comment alone on its line holds for its line and the line below it. Only a comment that starts with cchecker: ignore counts (not a string or a comment that mentions it); a doc comment (///, //!, /**) and a line inside a block comment that starts with it count too, as the line of that comment. It takes one or more codes, separated by commas or blanks, each of a tool (CC-GCC-, CC-TIDY-, CC-EFFECT-, CC-PATH- or CC-OWN-); a code that ends with * is a prefix (a * anywhere else is a usage error, and so is a word that only starts with ignore, such as ignore: or ignored):

/* cchecker: ignore CC-GCC-ANALYZER-MALLOC-LEAK: conn_free frees it through the struct */
p = malloc(n);
q = malloc(n); // cchecker: ignore CC-GCC-ANALYZER-*, CC-TIDY-CLANG-ANALYZER-UNIX-MALLOC: same as above

A finding of the rules belongs to a function: CC_IGNORE("CC-EFFECT-SHORT-BLOCKS", "reason") on any declaration of the function suppresses it (see Annotations). It takes codes of the rules only (checked when the rules run, so a run with --tools gcc does not see a wrong one). A suppression without a code or a reason, or with a code of no tool, is a usage error (exit 2).

When two suppressions hold for a finding, the reason of the nearer one is shown, and both count as used. --json lists the suppressed findings under suppressed, each with its reason, and the summary line counts them. Suppressions apply before the baseline, so a suppressed finding never goes into it.

Code
CC-UNUSED-IGNOREa code of a suppression matches no finding, once the run covered the tool of that code on that file (for the rules, a full run of a compile database)

The finding is at the comment or the function, one for each suppression, naming its stale codes. It never goes into the baseline: the fix is to edit or remove the comment.

A suppression is per code, not per message: one CC-GCC-ANALYZER-MALLOC-LEAK on a line hides every leak of that line, a new one too, so name only the codes that fire there. A finding is where its tool puts it: gcc reports one inside a macro at the line of the #define, so the comment goes there, not at the use. A suppression in a block that a configuration leaves out (#ifdef of a macro that is not defined) is reported unused on a run of that configuration. A suppression in a header is never reported unused: a header is read through the files that include it, each with its own configuration. A // comment that ends with \ goes on to the next line, and that line counts as a line of the comment.