Merge pull request #1035 from talktosam2003/format

docs/analyzer-suppressions.md describes

Author: Timi16

docs/analyzer-suppressions.md

@@ -21,7 +21,40 @@ location = "Dynamic trace"
 reason = "Intentional risk in test environments"
 ```
 
-- `rule_id`: ID of the rule being suppressed
-- `contract_path`: Substring of the contract path
-- `location`: Optional substring matching the location of the finding
+- `rule_id`: ID of the rule being suppressed (see [security-rules.md](security-rules.md) for a list of IDs)
+- `contract_path`: Substring of the contract path. Use `""` to match all contracts.
+- `location`: Optional substring matching the location of the finding. If omitted, all findings for the rule/contract are suppressed.
 - `reason`: Justification for ignoring the finding
+
+## Examples
+
+### Suppress a rule globally
+To ignore a rule across the entire project, use an empty `contract_path` and omit the `location`.
+
+```toml
+[[suppressions]]
+rule_id = "arithmetic"
+contract_path = ""
+reason = "Project uses a custom checked arithmetic wrapper that the analyzer doesn't yet recognize"
+```
+
+### Suppress a rule for a specific contract
+To ignore a rule only for certain files (e.g., test mocks), provide a substring of the path.
+
+```toml
+[[suppressions]]
+rule_id = "missing-auth"
+contract_path = "contracts/mocks/"
+reason = "Mock contracts intentionally bypass authorization for testing"
+```
+
+### Suppress a specific finding
+To ignore a specific finding within a contract, provide both the `contract_path` and the `location` string reported by the analyzer.
+
+```toml
+[[suppressions]]
+rule_id = "hardcoded-address"
+contract_path = "contracts/governance"
+location = "src/lib.rs:124"
+reason = "This is the hardcoded DAO treasury address, which is intentional"
+```

docs/issues/backlog-100-issues.md

@@ -78,7 +78,7 @@ Roadmap view: [Section C priorities](roadmap-priorities.md#section-c--feature-re
 - **I-026** `[DOC]` `docs/plugin-api.md` trust-policy section documents environment variables but doesn't cross-link to the plugin failure-handling doc.
 - **I-027** `[DOC]` `docs/plugin-failure-handling.md` (1956 bytes) covers session-level circuit-breaker behavior introduced in PR #902 but doesn't describe what happens to in-flight events when a plugin trips the breaker.
 - **I-028** `[DOC]` `docs/plugin-command-namespaces.md` (1435 bytes) is not linked from `docs/plugin-api.md`, so readers learning about custom commands won't discover the namespace conflict rules.
-- **I-029** `[DOC]` `docs/analyzer-suppressions.md` (822 bytes) describes the suppression file format but gives no example of a suppression that covers a whole rule vs. a specific finding.
+- **I-029** ~`[DOC]` `docs/analyzer-suppressions.md` (822 bytes) describes the suppression file format but gives no example of a suppression that covers a whole rule vs. a specific finding.~
 - **I-030** `[DOC]` `docs/security-rules.md` (854 bytes) lists rule codes but doesn't map each code to its description, severity, or remediation guidance.
 - **I-031** `[DOC]` `docs/wasm-artifact-metadata.md` (1716 bytes) documents the metadata fields but doesn't show an example `inspect --format json` output that contains them.
 - **I-032** `[DOC]` `docs/watch-mode.md` (744 bytes) mentions the watch command but doesn't document the polling interval, file-glob support, or debounce behavior.

docs/issues/roadmap-priorities.md

@@ -86,7 +86,7 @@ useful order instead of re-triaging the whole epic every time.
 | I-026 | Cross-link plugin-api.md trust section → plugin-failure-handling.md | P2 | XS | Docs | — | 2 |
 | I-027 | Document in-flight event behavior when plugin circuit-breaker trips | P1 | S | Docs | — | 2 |
 | I-028 | Link `plugin-command-namespaces.md` from `plugin-api.md` | P1 | XS | Docs | — | 1 |
-| I-029 | Add suppression examples (rule-level vs. finding-level) | P2 | S | Docs | — | 2 |
+| I-029 | ~Add suppression examples (rule-level vs. finding-level)~ | P2 | S | Docs | — | 2 |
 | I-030 | Expand `docs/security-rules.md` with severity and remediation guide | P2 | M | Docs | — | 2 |
 | I-031 | Add `inspect --format json` example output to `wasm-artifact-metadata.md` | P2 | S | Docs | — | 2 |
 | I-032 | Expand `docs/watch-mode.md` with polling interval and debounce details | P2 | S | Docs | — | 2 |

docs/security-rules.md

@@ -15,3 +15,6 @@ Rules supply robust metadata explicitly defined via the `SecurityRule` trait:
 3. **arithmetic**: Validates potential unbounded operation panics.
 4. **reentrancy**: Defends against nested external calls to untrusted code.
 5. **unbounded-iteration**: Defends against `Vec` bounds scaling out of control.
+
+## Suppressing Rules
+If a rule flags a finding that is an accepted risk or a false positive, you can suppress it using a suppression file. See [analyzer-suppressions.md](analyzer-suppressions.md) for details on the format and examples.

examples/README.md

@@ -45,4 +45,4 @@ This directory contains a variety of examples demonstrating the capabilities of
 
 *   **`*.json` (Snapshots & Traces)**: Sample ledger states (`snapshot.json`) and execution traces (`trace_a.json`) that can be loaded directly into the debugger.
 *   **`batch_args.json`**: Demonstrates how to run the debugger in batch mode for CI or automated auditing.
-*   **`analyzer-suppressions.toml`**: Example configuration for filtering security analyzer findings.
+*   **`analyzer-suppressions.toml`**: Example configuration for filtering security analyzer findings. See the [Analyzer Suppressions documentation](../docs/analyzer-suppressions.md) for usage details.