Suppression System
==================
SqC supports suppressing false positives via inline source comments or an external
TOML file. Each suppression includes a SHA-256 hash of the violation line, ensuring
suppressions break automatically when the underlying code changes.
Inline Comment Suppression
--------------------------
.. code-block:: c
// Line-before style (most common):
// SQC-SUPPRESS: ARR30-C HASH:a1b2c3d4e5f67890 JUSTIFICATION: "Bounds validated by caller"
arr[index] = value;
// Inline style (same line as violation):
arr[index] = value; // SQC-SUPPRESS: ARR30-C HASH:a1b2c3d4e5f67890 JUSTIFICATION: "Bounds checked"
// Stacked (multiple rules on one line):
// SQC-SUPPRESS: ERR00-C HASH:aaaa... JUSTIFICATION: "return captured in bytes_read"
// SQC-SUPPRESS: EXP34-C HASH:bbbb... JUSTIFICATION: "buf checked at function entry"
bytes_read = fread(buf, 1, file_size, fp);
Generate the hash with:
::
sqc --generate-suppression src/main.c:42:ARR30-C
External Suppression File
-------------------------
For read-only codebases, place a ``.sqc-suppress.toml`` in the project root
(auto-detected) or specify with ``--suppress-file``:
.. code-block:: toml
# .sqc-suppress.toml
[[suppression]]
file = "ringbuffer.c"
rule = "INT30-C"
hash = "a1f5861150a1e5b8"
justification = "Overflow checked by caller"
[[suppression]]
file = "src/utility.c"
rule = "EXP34-C"
hash = "b2c3d4e5f6a78901"
justification = "Pointer validated at function entry"
The ``file`` field matches by suffix -- ``ringbuffer.c`` matches any path ending
in ``ringbuffer.c``.
Wildcard Suppression
--------------------
For suppressing entire categories of violations without per-line hashes, use
``[[wildcard]]`` entries. All specified fields are ANDed — a violation must match
every field present. At least one matching field must be set.
.. code-block:: toml
# Suppress a rule for all files under a directory
[[wildcard]]
file_glob = "src/vendor/**"
rule = "DCL31-C"
justification = "Vendor code, not our responsibility"
# Suppress all DCL rules for vendor code
[[wildcard]]
file_glob = "src/vendor/**"
rule_glob = "DCL*"
justification = "All DCL rules suppressed for vendor code"
# Suppress by function name prefix in violation messages
[[wildcard]]
rule = "DCL31-C"
function_prefix = "wolfSSL_"
justification = "wolfSSL library functions declared in external headers"
# Combine multiple conditions (all must match)
[[wildcard]]
file_glob = "tests/**"
rule_glob = "MEM*"
justification = "Memory rules relaxed in test code"
**Fields:**
- ``file_glob`` — Glob pattern for file paths. Supports ``*`` (any characters
except ``/``), ``**`` (any characters including ``/``), and ``?`` (single
character). Matched as a suffix against the full file path.
- ``rule`` — Exact rule ID match (e.g., ``"DCL31-C"``).
- ``rule_glob`` — Glob pattern for rule IDs (e.g., ``"DCL*"``, ``"INT3?-C"``).
- ``function_prefix`` — Prefix to match in violation messages. Matches at word
boundaries, so ``"wolfSSL_"`` matches ``'wolfSSL_Init'`` but not
``'myWolfSSL_Init'``.
- ``justification`` — Explanation for the suppression (required).
Wildcard suppressions are checked after inline comment and hash-matched
suppressions. Hash-matched suppressions always take priority.
Hash Details
------------
- **Algorithm**: ``SHA-256(rule_id + ":" + whitespace_normalized(violation_line))``,
truncated to 16 hex characters
- **Rule-scoped**: different rules on the same line produce different hashes
- **Proximity matching**: inline comments match within 5 lines before the violation
- **Staleness detection**: if the violation line changes, the hash no longer matches
and the suppression stops working, forcing re-review