slang::WaiverManager class
#include <slang/diagnostics/WaiverManager.h>

The WaiverManager loads and manages diagnostic waiver rules from external TOML files.

It provides the ability to suppress diagnostics based on flexible matching criteria including file paths, hierarchy paths, diagnostic names, and source content patterns.

Evaluation model (see shouldWaive()):

  • Rules are evaluated in load order; the FIRST rule whose predicates all match wins. There is no priority/specificity scheme and no "deny" counterpart — a waiver can only suppress, never re-enable.
  • For a single rule, all configured predicates are AND'd: scope (file or hier), then optional diagnostic-name filter, then optional regex.
  • Waivers run AFTER -W severity remapping and –ignore-paths in DiagnosticEngine::issueImpl, so a waiver cannot promote a warning to an error and cannot resurrect a diagnostic already suppressed elsewhere.

Extending the schema: when adding a new TOML key, update the knownKeys allowlist in loadFromFile (otherwise it will be rejected as a typo) and add matching state to WaiverRule plus a corresponding predicate in shouldWaive.

Threading: like DiagnosticEngine, instances are not synchronized. Callers must ensure shouldWaive() is invoked single-threaded, which is the contract DiagnosticEngine::issue() already imposes.

Debugging: set the SLANG_WAIVER_DEBUG environment variable to any non-empty value to get per-rule trace output on stderr from shouldWaive().

Example TOML format:

[[waivers]]
file = "ip/**"                          # waive all diagnostics in these files

[[waivers]]
file = "tb/**/*.sv"
diagnostic = ["unused-variable", "width-trunc"]

[[waivers]]
file = "rtl/core.sv"                    # waive specific occurrence via line content
diagnostic = "unused-variable"
regex = '\bdebug_reg\b'                  # literal string: no escape soup

[[waivers]]
hier = "top/u_subsys/u_conv"            # waive by hierarchy
diagnostic = "width-trunc"

[[waivers]]
hier = "**/u_debug*"
diagnostic = "unused-variable"
regex = '\bdbg_status\b'

Public functions

bool loadFromFile(const std::filesystem::path& path, const DiagnosticEngine& diagnosticEngine, std::string& errors)
Load waiver rules from a TOML file, appending to any already loaded.
bool shouldWaive(const Diagnostic& diagnostic, SourceLocation location, const SourceManager& sourceManager, const DiagnosticEngine& diagnosticEngine)
Check if a diagnostic should be waived based on the loaded rules.
size_t getAppliedCount() const
Get how many times waivers were applied.
size_t getUnusedCount() const
Get how many rules were never hit.
std::string getSummary(bool showUnused = false) const
Render a summary of unused waivers for logging.

Function documentation

bool slang::WaiverManager::loadFromFile(const std::filesystem::path& path, const DiagnosticEngine& diagnosticEngine, std::string& errors)

Load waiver rules from a TOML file, appending to any already loaded.

Parameters
path The path to the TOML waiver file
diagnosticEngine Used to validate diagnostic option names at load time (so misspelled diagnostic names fail loudly instead of silently never matching). Warning options must already be configured on the engine before this call so that user-defined groups resolve.
errors Output parameter for error messages (if any)
Returns true if the file was loaded successfully, false otherwise

Multiple loads are purely additive — there is no de-dup, no override, and load order determines the first-match-wins precedence used by shouldWaive(). On parse failure rules already accepted from prior calls are preserved; rules from the failing file are not partially applied because each rule is push_back'd only after the entry fully validates.

bool slang::WaiverManager::shouldWaive(const Diagnostic& diagnostic, SourceLocation location, const SourceManager& sourceManager, const DiagnosticEngine& diagnosticEngine)

Check if a diagnostic should be waived based on the loaded rules.

Parameters
diagnostic The diagnostic to check
location The source location of the diagnostic
sourceManager The source manager for accessing file information
diagnosticEngine The diagnostic engine for accessing diagnostic metadata
Returns true if the diagnostic should be waived (suppressed), false otherwise

Returns true on the FIRST rule that matches; later rules are not consulted (so order is significant). Side effect: updates per-rule statistics on every call regardless of result, including on partial matches that later predicates reject — these stats feed getSummary().