Adding waiver file support

[sjalloq]

I'm fairly new to using slang but the one feature it's missing to become my go to linting tool is support for standalone waiver files. Generally, in my experience, using inline waivers is a no-no and there are cases where you simply can't use them, for example when you need to waive lint errors/warnings in external IP.

So as an ice breaker to this discussion, I've vibe coded a first pass that should hopefully provide some context and discussion points. See master...sjalloq:slang:feat/add_waiver_file_support for the diffs.

The waiver file(s) are in YAML format and provide a number of options:

# Waiver examples for slang
# --------------------------
# This YAML demonstrates each supported waiver type and how it applies.
# Notes:
# - file_glob is matched against full file paths; wildcards allow portability across workspaces.
# - Scoped waivers (everything except "file" / "diagnostic_file") are enforced to match a single file,
#   even if the glob could match multiple paths.
# - hier_regex and signal filters require diagnostics that carry symbol/hierarchy info.

waivers:
  # Waive all diagnostics in matching files (broad hammer; use sparingly).
  - type: file
    file_glob: ".../third_party/ip/*.sv"
    author: "ip_team"
    comment: "3rd-party IP; waive all tool diagnostics in vendor drop."
    # Waives every diagnostic reported from any matching file.

  # Waive a specific diagnostic across matching files (keeps other warnings).
  - type: diagnostic_file
    diagnostic: width-trunc
    file_glob: ".../legacy/blocks/*.sv"
    author: "firstname.lastname"
    comment: "Legacy block under review; width truncation accepted by design."
    # Only suppresses width-trunc in these files; other diags still report.

  # Waive a single diagnostic on an exact line.
  - type: diagnostic_line_number
    diagnostic: unused-variable
    file_glob: ".../rtl/foo/bar.sv"
    line_number: 128
    author: "user@example.com"
    comment: |
      TODO: remove temp register after refactor.
      Waive unused-variable on this line only.
    # Applies to the first file matching the glob; waived only on line 128.

  # Waive a diagnostic on a specific line span.
  - type: diagnostic_line_span
    diagnostic: implicit-convert
    file_glob: ".../rtl/baz/qux.sv"
    line_span:
      start: 200
      end: 205
    author: "username"
    comment: "Known truncation in legacy interface; spec mandates 6-bit field."
    # Suppresses implicit-convert between lines 200-205 in the first matching file.

  # Waive a diagnostic when the source line matches a regex.
  - type: diagnostic_line_regex
    diagnostic: unused-variable
    file_glob: ".../rtl/top/data_path.sv"
    line_regex: "\\btemp_data\\b"
    author: "qa@example.com"
    comment: "temp_data is a debug-only signal, intentionally unused in production."
    # Waives unused-variable only on lines containing "temp_data" in the first matching file.

  # Waive a diagnostic for a specific instance (hierarchy path).
  - type: diagnostic_instance
    diagnostic: width-trunc
    file_glob: ".../rtl/lib/y.sv"
    hier_regex: "u_y0$"
    author: "john.doe"
    comment: "Instance u_y0 feeds a 3-bit legacy bus; truncation is intentional."
    # Suppresses width-trunc only when reported on instance paths ending in "u_y0".

I've tried to allow the common waiver types I've seen before but this definitely isn't an exhaustive list and there are still quite a lot of holes in the logic that would need reviewing. But I think it's a good MVP that provides enough functionality for people to have a play.

[svenka3]

I would also like to see this. Along with potential waiver file converters from other opensource linters as well as commercial ones (if licensing schemes allow). I would like to extend this to SVA, Testbench and UVM as well.

[MikePopoloski]

I'm not against having support for this. The proposed YAML seems nice enough to me but I would like to know more about the file formats used by other lint tools and whether we ought to be consuming those natively instead.

[sjalloq]

I think the problem is that every tool does it differently. I can probably pull together examples for Verilator, HAL and Jasper. I don't have access to Spyglass. Perhaps someone else could look at that.

[svenka3]

Maybe we can trust/start with this GenAI snippet:

## 1. Waive specific Width Mismatch on a known legacy line
waive -rule W164a -file "*/rtl/core_alu.sv" -line 128 -comment "Legacy bit-width mismatch, safe by design"

## 2. Waive "Unused Signal" (W123) for all parameters in the 'include' directory
# Uses wildcards (*) to match any file in that folder
waive -rule W123 -file "*/include/*.svh" -comment "Parameters in headers often unused in specific modules"

## 3. Waive based on Message Pattern (Regex)
# Ignores combinational loops if the message mentions the specific signal "gen_grant_loop"
waive -rule W504 -msg "*gen_grant_loop*" -comment "Intentional ring oscillator logic for entropy"

## 4. Block-level Waiver (Waive Rule entirely for a file)
# Ignores all Case Statement violations in the decoder
waive -rule W263 -file "*/rtl/decoder.sv" -comment "Decoder uses full_case parallel_case extensively"

[MikePopoloski]

I would not trust an LLM to not make stuff up. Absent an existing use case that someone wants supported I'd rather just go with a format we think makes sense.

[svenka3]

The above LLM generated is NOT a suggestion for slang's proposed waiver file, I prefer that YAML (will look deeper if we proceed with it from UVM/TB dynamic scopes if needed). Rather a sample of what other tool(s) may support.

[sjalloq]

It's been a while since I used Spyglass but the examples above look familiar. In fact here are some examples.

Verilator's format is described in their docs - have a look for lint_off.

The general format is:

// User comment
lint_off -rule WIDTH -file "$PROJ_ROOT/path/to/file.sv" -match "*wildcard message"

although I always have trouble with the syntax of the wildcard matching and it fails silently. There are a few GitHub issues about how to correctly apply the waivers.

For HAL, it's very similar, also with the ability to specify a pattern to match against:

lint_checking file = $PROJ_ROOT/path/to/file.sv {
    RULE1 off ;
    RULE2 { pattern = "*some_signal*" } off ; // Comment
}

What I was trying to do with the YAML format was build on these and allow the corner cases that I've come across in the past. So I wanted to be able to exclude full hierarchies to filter out IP blocks that you can't touch and also add support for regex matching against instances rather than just modules. The rest lines up with the above examples I think.

It's generally preferable to always use a regex match as line numbers change during development. I'm now having flashbacks to tools I've written that searched around the line numbers of unused waivers to see if it could find them and update.