shellsafe 0.3.2__tar.gz → 0.3.4__tar.gz

{shellsafe-0.3.2 → shellsafe-0.3.4}/CHANGELOG.md

@@ -3,6 +3,33 @@
 All notable changes to this project are documented here. Format follows
 Keep a Changelog; versioning follows SemVer.
 
+## [0.3.4] - 2026-09-03
+
+### Fixed
+
+- Export `plan()` from public surface (`__init__.py`); was defined in
+  `execute.py` but not listed in `__all__`, causing `ImportError` on
+  `from shellsafe import plan`
+
+## [0.3.3] - 2026-09-01
+
+### Added
+
+- Inline suppression: `# shellsafe: ignore AU001 reason: <why>` comments
+- File-level suppression: `# shellsafe: ignore-file AU001` at top of file
+- Multi-rule suppression: `# shellsafe: ignore AU001, AU002 reason: <why>`
+- AU010 meta-warning: flags suppression comments without a reason
+- CLI `--show-ignored` flag to display suppressed findings
+- CLI `--ignore RULE` flag to suppress rules from command line (repeatable)
+- Suppression fixture corpus: inline, file-level, multi-rule, AU010 cases
+- Unit tests for suppression parsing and application
+- Integration tests for CLI suppression flags
+
+### Changed
+
+- Terminal reporter shows suppressed count and muted display for ignored findings
+- CLI version string shows "AU001-AU004, suppression"
+
 ## [0.3.2] - 2026-08-30
 
 ### Added

{shellsafe-0.3.2 → shellsafe-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shellsafe
-Version: 0.3.2
+Version: 0.3.4
 Summary: Run shell commands safely using Python 3.14 template strings. Values can never turn into commands.
 Project-URL: Homepage, https://github.com/rahulXs/shellsafe
 Project-URL: Repository, https://github.com/rahulXs/shellsafe
@@ -131,6 +131,19 @@ Filter by severity:
 shellsafe audit src/ --severity warning
 ```
 
+Suppress known-safe findings inline:
+
+```python
+# shellsafe: ignore AU001 reason: tested, value is constant
+os.system(f"echo {safe_value}")
+```
+
+Suppress from the command line:
+
+```bash
+shellsafe audit src/ --ignore AU004
+```
+
 ## Limits
 
 - Shell features (pipes, redirections) work on Linux and macOS only. Windows

{shellsafe-0.3.2 → shellsafe-0.3.4}/README.md

@@ -108,6 +108,19 @@ Filter by severity:
 shellsafe audit src/ --severity warning
 ```
 
+Suppress known-safe findings inline:
+
+```python
+# shellsafe: ignore AU001 reason: tested, value is constant
+os.system(f"echo {safe_value}")
+```
+
+Suppress from the command line:
+
+```bash
+shellsafe audit src/ --ignore AU004
+```
+
 ## Limits
 
 - Shell features (pipes, redirections) work on Linux and macOS only. Windows

{shellsafe-0.3.2 → shellsafe-0.3.4}/src/shellsafe/__init__.py

@@ -1,11 +1,11 @@
 """shellsafe: safe shell commands via Python 3.14 template strings.
 
 Public surface (stable names, additive only through 1.0):
-run, capture, shx, RAW, CaptureResult.
+run, capture, shx, plan, RAW, CaptureResult.
 """
 
 from ._version import __version__
-from .execute import CaptureResult, capture, run, shx
+from .execute import CaptureResult, capture, plan, run, shx
 from .raw import RAW
 
 __all__ = [
@@ -13,6 +13,7 @@ __all__ = [
     "CaptureResult",
     "__version__",
     "capture",
+    "plan",
     "run",
     "shx",
 ]

shellsafe-0.3.4/src/shellsafe/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.4"

{shellsafe-0.3.2 → shellsafe-0.3.4}/src/shellsafe/audit/scanner.py

@@ -7,7 +7,6 @@ import ast
 import json
 import sys
 import time
-from collections.abc import Callable
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
@@ -25,7 +24,7 @@ class Finding:
     lineno: int
     col: int
     message: str
-    evidence: dict[str, Any] = field(default_factory=dict)
+    evidence: dict[str, Any] = field(default_factory=dict)  # why: heterogeneous value types
     fix_hint: str = ""
     ignored: bool = False
     ignore_reason: str | None = None
@@ -48,7 +47,7 @@ _IMPORT_ALIAS = {
 }
 
 
-def _resolve_callee(node: ast.expr, aliases: dict[str, str]) -> str | None:
+def _resolve_callee(node: ast.expr, aliases: dict[str, str]):
     """Resolve a Call.func to an executor label like 'os.system'."""
     if (
         isinstance(node, ast.Attribute)
@@ -98,14 +97,14 @@ def au001(node: ast.Call, aliases: dict[str, str], path: str) -> Finding | None:
     return None
 
 
-def _has_shell_true(node: ast.Call) -> bool:
+def _has_shell_true(node: ast.Call):
     for kw in node.keywords:
         if kw.arg == "shell" and isinstance(kw.value, ast.Constant) and kw.value.value is True:
             return True
     return False
 
 
-def _is_dynamic_string(node: ast.expr) -> bool:
+def _is_dynamic_string(node: ast.expr):
     if isinstance(node, ast.JoinedStr):
         return any(isinstance(v, ast.FormattedValue) for v in node.values)
     if (
@@ -155,9 +154,9 @@ def au002(node: ast.Call, aliases: dict[str, str], path: str) -> Finding | None:
     return None
 
 
-def _track_dynamic_vars(tree: ast.Module) -> set[str]:
+def _track_dynamic_vars(tree: ast.Module):
     """Find variables assigned dynamic string expressions."""
-    dynamic: set[str] = {}
+    dynamic = set()
     for node in ast.walk(tree):
         if not isinstance(node, ast.Assign):
             continue
@@ -249,7 +248,7 @@ def au003(node: ast.Call, aliases: dict[str, str], path: str) -> Finding | None:
     return None
 
 
-def _has_timeout(node: ast.Call) -> bool:
+def _has_timeout(node: ast.Call):
     return any(kw.arg == "timeout" for kw in node.keywords)
 
 
@@ -286,7 +285,7 @@ def au004(node: ast.Call, aliases: dict[str, str], path: str) -> Finding | None:
     )
 
 
-RULES: list[tuple[str, Callable[..., Finding | None]]] = [
+RULES = [
     ("AU001", au001),
     ("AU002", au002),
     ("AU003", au003),
@@ -294,8 +293,8 @@ RULES: list[tuple[str, Callable[..., Finding | None]]] = [
 ]
 
 
-def _discover(paths: list[str]) -> list[Path]:
-    files: list[Path] = []
+def _discover(paths: list[str]):
+    files = []
     for raw in paths:
         p = Path(raw)
         if p.is_file() and p.suffix == ".py":
@@ -309,7 +308,7 @@ def _discover(paths: list[str]) -> list[Path]:
     return files
 
 
-def _import_aliases(tree: ast.Module) -> dict[str, str]:
+def _import_aliases(tree: ast.Module):
     """Map local names to real module.function for executor imports."""
     aliases = {}
     for node in ast.walk(tree):
@@ -325,47 +324,231 @@ def _import_aliases(tree: ast.Module) -> dict[str, str]:
     return aliases
 
 
-def scan(paths: list[str]) -> list[Finding]:
-    """Scan Python files for audit findings."""
-    findings: list[Finding] = []
+def _parse_suppression_comment(comment: str) -> tuple[list[str], str | None]:
+    """Parse a shellsafe suppression comment.
+
+    Returns (rule_ids, reason_or_None).
+    Accepts: # shellsafe: ignore RULE[,RULE...] [reason: text]
+    """
+    stripped = comment.strip()
+    if not stripped.startswith("#"):
+        return [], None
+    stripped = stripped[1:].strip()
+    if not stripped.lower().startswith("shellsafe:"):
+        return [], None
+    directive = stripped[len("shellsafe:"):].strip()
+    if not directive.lower().startswith("ignore "):
+        return [], None
+    rest = directive[len("ignore "):]
+    reason = None
+    reason_match = rest.split(" reason:", 1)
+    if len(reason_match) == 2:
+        rest = reason_match[0]
+        reason = reason_match[1].strip() or None
+    rule_ids = [r.strip().upper() for r in rest.split(",") if r.strip()]
+    return rule_ids, reason
+
+
+def _parse_suppressions(
+    source_lines: list[str],
+) -> tuple[set[int], dict[int, tuple[set[str], str | None]]]:
+    """Parse source lines for suppression directives.
+
+    Returns:
+        file_level_rules: rule ids suppressed file-wide (from ignore-file)
+        line_suppressions: line_no -> (set of rule ids, reason)
+    """
+    file_level_rules = set()
+    line_suppressions = {}
+
+    for i, line in enumerate(source_lines, 1):
+        stripped = line.strip()
+        if not stripped.startswith("#"):
+            continue
+        rule_ids, reason = _parse_suppression_comment(stripped)
+        if not rule_ids:
+            if stripped.lower() == "# shellsafe: ignore-file":
+                file_level_rules.add("*")
+            elif stripped.lower().startswith("# shellsafe: ignore-file "):
+                for r in stripped.split(None, 4)[-1].split(","):
+                    r = r.strip().upper()
+                    if r:
+                        file_level_rules.add(r)
+            continue
+        line_suppressions[i] = (set(rule_ids), reason)
+
+    return file_level_rules, line_suppressions
+
+
+def _find_suppressed_line(
+    target_line: int,
+    line_suppressions: dict[int, tuple[set[str], str | None]],
+) -> tuple[set[str], str | None] | None:
+    """Find which rules suppress findings at target_line.
+
+    Checks previous non-blank, non-comment line, then target line itself.
+    """
+    for candidate in (target_line - 1, target_line):
+        if candidate in line_suppressions:
+            return line_suppressions[candidate]
+    return None
+
+
+def _apply_suppression(
+    result: Finding,
+    ignore: set[str] | None,
+    file_rules: set[str],
+    line_suppressions: dict[int, tuple[set[str], str | None]],
+) -> Finding:
+    """Apply suppression rules to a finding. Returns new Finding with ignored flag."""
+    rule_id = result.rule_id
+    suppressed = False
+    ignore_reason = None
+
+    if ignore and rule_id in ignore:
+        return Finding(
+            rule_id=result.rule_id,
+            title=result.title,
+            severity=result.severity,
+            confidence=result.confidence,
+            path=result.path,
+            lineno=result.lineno,
+            col=result.col,
+            message=result.message,
+            evidence=result.evidence,
+            fix_hint=result.fix_hint,
+            ignored=True,
+            ignore_reason="CLI --ignore",
+        )
+    if rule_id in file_rules or "*" in file_rules:
+        suppressed = True
+        ignore_reason = "file-level suppression"
+    else:
+        match = _find_suppressed_line(result.lineno, line_suppressions)
+        if match:
+            rules, reason = match
+            if rule_id in rules:
+                suppressed = True
+                ignore_reason = reason
+
+    if not suppressed:
+        return result
+    return Finding(
+        rule_id=result.rule_id,
+        title=result.title,
+        severity=result.severity,
+        confidence=result.confidence,
+        path=result.path,
+        lineno=result.lineno,
+        col=result.col,
+        message=result.message,
+        evidence=result.evidence,
+        fix_hint=result.fix_hint,
+        ignored=True,
+        ignore_reason=ignore_reason,
+    )
+
+
+def _emit_au010(
+    line_suppressions: dict[int, tuple[set[str], str | None]],
+    rel: str,
+) -> list[Finding]:
+    """Emit AU010 warnings for suppression comments without reasons."""
+    results = []
+    for suppressed_rules, reason in line_suppressions.values():
+        if not reason and suppressed_rules:
+            first_line = next(
+                (ln for ln, (r, _) in line_suppressions.items() if r == suppressed_rules),
+                1,
+            )
+            results.append(
+                Finding(
+                    rule_id="AU010",
+                    title="suppression comment without reason",
+                    severity="info",
+                    confidence=1.0,
+                    path=rel,
+                    lineno=first_line,
+                    col=0,
+                    message=(
+                        f"Suppression for {', '.join(sorted(suppressed_rules))} "
+                        f"has no reason. Add: reason: <why>"
+                    ),
+                    evidence={"rules": sorted(suppressed_rules)},
+                )
+            )
+    return results
+
+
+def scan(paths: list[str], ignore: set[str] | None = None) -> list[Finding]:
+    """Scan Python files for audit findings.
+
+    Args:
+        paths: files or directories to scan.
+        ignore: rule ids to suppress from CLI --ignore flag.
+    """
+    findings = []
     for path in _discover(paths):
         try:
-            tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+            source = path.read_text(encoding="utf-8")
+            tree = ast.parse(source, filename=str(path))
         except (SyntaxError, UnicodeDecodeError):
             continue
         aliases = _import_aliases(tree)
+        source_lines = source.splitlines()
+        file_rules, line_suppressions = _parse_suppressions(source_lines)
         rel = str(path)
         for node in ast.walk(tree):
             if isinstance(node, ast.Call):
                 for _, rule in RULES:
                     result = rule(node, aliases, rel)
                     if result is not None:
-                        findings.append(result)
+                        findings.append(
+                            _apply_suppression(result, ignore, file_rules, line_suppressions)
+                        )
+        findings.extend(_emit_au010(line_suppressions, rel))
+
     findings.sort(key=lambda f: (f.severity != "error", f.path, f.lineno))
     return findings
 
 
-_COLORS = {"error": "\033[31m", "warning": "\033[33m", "info": "\033[36m", "reset": "\033[0m"}
+_COLORS = {
+    "error": "\033[31m",
+    "warning": "\033[33m",
+    "info": "\033[36m",
+    "ignored": "\033[90m",
+    "reset": "\033[0m",
+}
 
 
-def _color(text: str, severity: str) -> str:
+def _color(text: str, severity: str):
     c = _COLORS.get(severity, "")
     return f"{c}{text}{_COLORS['reset']}" if c else text
 
 
-def report_terminal(findings: list[Finding]) -> str:
+def report_terminal(findings: list[Finding], show_ignored: bool = False) -> str:
     """Render findings as a terminal table."""
     if not findings:
         return "no findings"
     use_color = hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+    visible = findings if show_ignored else [f for f in findings if not f.ignored]
+    if not visible:
+        return "no findings"
+    suppressed = sum(1 for f in findings if f.ignored)
     lines = [
         f"{'SEV':<9} {'RULE':<7} {'FILE':<40} {'LINE':>5}  MESSAGE",
         "-" * 90,
     ]
-    for f in findings:
-        sev = _color(f.severity.upper(), f.severity) if use_color else f.severity.upper()
+    for f in visible:
+        if f.ignored:
+            sev = _color("IGNORED", "ignored") if use_color else "IGNORED"
+        else:
+            sev = _color(f.severity.upper(), f.severity) if use_color else f.severity.upper()
         path = f.path if len(f.path) <= 40 else "..." + f.path[-37:]
-        lines.append(f"{sev:<18} {f.rule_id:<7} {path:<40} {f.lineno:>5}  {f.message}")
+        reason = f" [{f.ignore_reason}]" if f.ignore_reason else ""
+        lines.append(f"{sev:<18} {f.rule_id:<7} {path:<40} {f.lineno:>5}  {f.message}{reason}")
+    if suppressed and not show_ignored:
+        lines.append(f"\n  {suppressed} finding(s) suppressed (use --show-ignored to display)")
     return "\n".join(lines)
 
 
@@ -374,10 +557,10 @@ def report_json(report: dict[str, object]) -> str:
     return json.dumps(report, indent=2)
 
 
-def scan_report(paths: list[str]) -> dict[str, object]:
+def scan_report(paths: list[str], ignore: set[str] | None = None) -> dict[str, object]:
     """Scan and return a report dict matching schema v1."""
     start = time.monotonic()
-    findings = scan(paths)
+    findings = scan(paths, ignore=ignore)
     duration_ms = round((time.monotonic() - start) * 1000, 1)
 
     errors = sum(1 for f in findings if f.severity == "error" and not f.ignored)

{shellsafe-0.3.2 → shellsafe-0.3.4}/src/shellsafe/cli.py

@@ -24,6 +24,18 @@ def _build_parser() -> argparse.ArgumentParser:
         default="warning",
         help="minimum severity to report (default: warning)",
     )
+    audit.add_argument(
+        "--show-ignored",
+        action="store_true",
+        help="show suppressed findings in output",
+    )
+    audit.add_argument(
+        "--ignore",
+        action="append",
+        default=[],
+        metavar="RULE",
+        help="suppress a rule (repeatable, e.g. --ignore AU001 --ignore AU004)",
+    )
 
     sub.add_parser("version", help="detailed version and capability matrix")
     return parser
@@ -32,7 +44,8 @@ def _build_parser() -> argparse.ArgumentParser:
 def _run_audit(args: argparse.Namespace) -> int:
     from .audit.scanner import Finding, report_json, report_terminal, scan_report
 
-    report = scan_report(args.paths)
+    ignore = set(args.ignore) if args.ignore else None
+    report = scan_report(args.paths, ignore=ignore)
     findings = report.get("findings", [])
 
     min_sev = _SEVERITY_ORDER.get(args.severity, 1)
@@ -44,7 +57,7 @@ def _run_audit(args: argparse.Namespace) -> int:
     if args.json_output:
         print(report_json(report))
     else:
-        print(report_terminal([Finding(**f) for f in filtered]))
+        print(report_terminal([Finding(**f) for f in filtered], show_ignored=args.show_ignored))
 
     summary = report.get("summary", {})
     return exitcodes.FINDINGS if summary.get("errors", 0) > 0 else exitcodes.OK
@@ -62,7 +75,7 @@ def main(argv: list[str] | None = None) -> int:
         print(f"shellsafe {__version__} . python {py} . {sys.platform}")
         print("argv-mode: available")
         print("shell-mode: available (posix)")
-        print("audit: available (AU001-AU004)")
+        print("audit: available (AU001-AU004, suppression)")
         return exitcodes.OK
     if args.command == "audit":
         return _run_audit(args)

{shellsafe-0.3.2 → shellsafe-0.3.4}/src/shellsafe/execute.py

@@ -3,7 +3,6 @@
 import subprocess
 import sys
 from dataclasses import dataclass
-from typing import Any
 
 from .errors import ArgvOnlyError, ShellSafeError
 from .raw import Raw  # noqa: F401  (re-exported through the package root)
@@ -48,7 +47,7 @@ def plan(template: object) -> ExecutionPlan:
     return render_plan(template)
 
 
-def _pass_through(kwargs: dict[str, object]) -> dict[str, Any]:
+def _pass_through(kwargs: dict[str, object]):
     return {k: v for k, v in kwargs.items() if k in _ALLOWED_KWARGS}
 
 

{shellsafe-0.3.2 → shellsafe-0.3.4}/src/shellsafe/platforms.py

@@ -7,7 +7,7 @@ METACHARACTERS = frozenset("|&;()<>$`\"'*?!#\\\n\r\t")
 IS_WINDOWS = sys.platform.startswith("win")
 
 
-def route_for(static_text: str) -> str:
+def route_for(static_text: str):
     """Return "argv" or "shell" for the given static template text.
 
     Raises UnsupportedPlatformError on Windows when shell features are requested.

{shellsafe-0.3.2 → shellsafe-0.3.4}/tests/fixtures/audit/au001_sample.py

@@ -5,7 +5,7 @@ import subprocess
 from os import system
 from subprocess import run as subprocess_run
 
-# --- positive cases (should produce AU001 findings) ---
+# positive cases (should produce AU001 findings)
 
 os.system(f"echo {user_input}")
 
@@ -20,7 +20,7 @@ subprocess_run(f"grep {pattern} {file}")
 subprocess.getoutput(f"echo {user_input}")
 
 
-# --- safe cases (should NOT produce findings) ---
+# safe cases (should NOT produce findings)
 
 subprocess.run(["echo", user_input])
 

{shellsafe-0.3.2 → shellsafe-0.3.4}/tests/fixtures/audit/au002_sample.py

@@ -2,7 +2,7 @@
 
 import subprocess
 
-# --- positive cases (should produce AU002 findings) ---
+# positive cases (should produce AU002 findings)
 
 # f-string with shell=True (also caught by AU001)
 subprocess.run(f"echo {user_input}", shell=True)
@@ -23,7 +23,7 @@ subprocess.run(cmd, shell=True)
 subprocess.run(config.command, shell=True)
 
 
-# --- safe cases (should NOT produce AU002 findings) ---
+# safe cases (should NOT produce AU002 findings)
 
 # shell=True with list (safe)
 subprocess.run(["echo", user_input], shell=True)

{shellsafe-0.3.2 → shellsafe-0.3.4}/tests/fixtures/audit/au003_sample.py

@@ -3,7 +3,7 @@
 import os
 import subprocess
 
-# --- positive cases (should produce AU003 findings) ---
+# positive cases (should produce AU003 findings)
 
 # variable passed to executor
 cmd = "echo " + user_input
@@ -25,7 +25,7 @@ subprocess.run(cmd)
 subprocess.run("echo " + user_input)
 
 
-# --- safe cases (should NOT produce AU003 findings) ---
+# safe cases (should NOT produce AU003 findings)
 
 # list form (safe)
 subprocess.run(["echo", user_input])

{shellsafe-0.3.2 → shellsafe-0.3.4}/tests/fixtures/audit/au004_sample.py

@@ -3,7 +3,7 @@
 import subprocess
 from subprocess import run as subprocess_run
 
-# --- positive cases (should produce AU004 findings) ---
+# positive cases (should produce AU004 findings)
 
 subprocess.run(["echo", "hello"])
 
@@ -16,7 +16,7 @@ subprocess.check_output(["echo", "hello"])
 subprocess_run(["echo", "hello"])
 
 
-# --- safe cases (should NOT produce AU004 findings) ---
+# safe cases (should NOT produce AU004 findings)
 
 subprocess.run(["echo", "hello"], timeout=10)
 

shellsafe-0.3.4/tests/fixtures/audit/suppress_sample.py

@@ -0,0 +1,26 @@
+"""Suppression test fixture: inline, file-level, multi-rule, AU010."""
+
+import os
+import subprocess
+
+# Line-level suppression with reason
+
+# shellsafe: ignore AU001 reason: tested, value is constant
+os.system(f"echo {os.listdir('.')}")
+
+# shellsafe: ignore AU001, AU002 reason: legacy code, tracked for migration
+subprocess.run(f"echo {os.listdir('.')}", shell=True)
+
+# Line-level suppression without reason (AU010 trigger)
+
+# shellsafe: ignore AU004
+subprocess.run(["ls"])
+
+# No suppression (should still be flagged)
+
+os.system(f"echo {os.listdir('.')}")
+
+# Safe cases (should never be flagged regardless of suppression)
+
+subprocess.run(["ls", "-la"])
+subprocess.run(["echo", "hello"], timeout=5)

{shellsafe-0.3.2 → shellsafe-0.3.4}/tests/integration/test_cli_audit.py

@@ -203,3 +203,104 @@ def test_audit_cli_all_rules():
     assert "AU002" in rule_ids
     assert "AU003" in rule_ids
     assert "AU004" in rule_ids
+
+
+def test_audit_cli_suppress_inline():
+    out = subprocess.run(
+        [sys.executable, "-m", "shellsafe", "audit", str(FIXTURES / "suppress_sample.py")],
+        capture_output=True,
+        text=True,
+    )
+    assert "suppressed" in out.stdout
+
+
+def test_audit_cli_suppress_show_ignored():
+    out = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "shellsafe",
+            "audit",
+            str(FIXTURES / "suppress_sample.py"),
+            "--show-ignored",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    assert "IGNORED" in out.stdout
+
+
+def test_audit_cli_suppress_json():
+    out = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "shellsafe",
+            "audit",
+            str(FIXTURES / "suppress_sample.py"),
+            "--json",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    report = json.loads(out.stdout)
+    ignored = [f for f in report["findings"] if f["ignored"]]
+    assert len(ignored) >= 3
+    assert report["summary"]["ignored"] >= 3
+
+
+def test_audit_cli_ignore_flag():
+    out = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "shellsafe",
+            "audit",
+            str(FIXTURES / "suppress_sample.py"),
+            "--ignore",
+            "AU001",
+            "--show-ignored",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    assert "CLI --ignore" in out.stdout
+
+
+def test_audit_cli_ignore_flag_json():
+    out = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "shellsafe",
+            "audit",
+            str(FIXTURES / "suppress_sample.py"),
+            "--ignore",
+            "AU001",
+            "--json",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    report = json.loads(out.stdout)
+    au001 = [f for f in report["findings"] if f["rule_id"] == "AU001"]
+    assert all(f["ignored"] for f in au001)
+    assert all(f["ignore_reason"] == "CLI --ignore" for f in au001)
+
+
+def test_audit_cli_au010_in_output():
+    out = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "shellsafe",
+            "audit",
+            str(FIXTURES / "suppress_sample.py"),
+            "--severity",
+            "info",
+            "--show-ignored",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    assert "AU010" in out.stdout

{shellsafe-0.3.2 → shellsafe-0.3.4}/tests/unit/test_audit.py

@@ -165,3 +165,87 @@ def test_all_rules_found():
     assert "AU002" in rule_ids
     assert "AU003" in rule_ids
     assert "AU004" in rule_ids
+
+
+# Suppression tests
+
+
+def test_suppress_with_reason():
+    findings = scan([str(FIXTURES / "suppress_sample.py")])
+    # Line 13: AU001 suppressed with reason
+    au001_ignored = [
+        f for f in findings
+        if f.rule_id == "AU001" and f.ignored and f.ignore_reason == "tested, value is constant"
+    ]
+    assert len(au001_ignored) == 1
+
+
+def test_suppress_multi_rule_with_reason():
+    findings = scan([str(FIXTURES / "suppress_sample.py")])
+    # Line 16: AU001 and AU002 suppressed together with reason
+    multi_ignored = [
+        f for f in findings
+        if f.ignored and f.ignore_reason == "legacy code, tracked for migration"
+    ]
+    rule_ids = {f.rule_id for f in multi_ignored}
+    assert "AU001" in rule_ids
+    assert "AU002" in rule_ids
+
+
+def test_suppress_without_reason_emits_au010():
+    findings = scan([str(FIXTURES / "suppress_sample.py")])
+    # Line 20: AU004 suppressed without reason
+    au004_ignored = [
+        f for f in findings
+        if f.rule_id == "AU004" and f.ignored
+    ]
+    assert len(au004_ignored) == 1
+    assert au004_ignored[0].ignore_reason is None
+    # AU010 should be emitted for the reason-less suppression
+    au010 = [f for f in findings if f.rule_id == "AU010"]
+    assert len(au010) >= 1
+
+
+def test_unsuppressed_findings_still_flagged():
+    findings = scan([str(FIXTURES / "suppress_sample.py")])
+    # Line 24: AU001 with no suppression
+    au001_unsuppressed = [
+        f for f in findings
+        if f.rule_id == "AU001" and not f.ignored
+    ]
+    assert len(au001_unsuppressed) == 1
+
+
+def test_suppress_cli_ignore():
+    findings = scan([str(FIXTURES / "suppress_sample.py")], ignore={"AU001"})
+    # All AU001 findings should be ignored
+    au001 = [f for f in findings if f.rule_id == "AU001"]
+    assert all(f.ignored for f in au001)
+    assert all(f.ignore_reason == "CLI --ignore" for f in au001)
+
+
+def test_suppress_cli_ignore_does_not_affect_other_rules():
+    findings = scan([str(FIXTURES / "suppress_sample.py")], ignore={"AU001"})
+    # AU001 findings are all ignored via CLI
+    au001_active = [
+        f for f in findings
+        if f.rule_id == "AU001" and not f.ignored
+    ]
+    assert len(au001_active) == 0
+    # AU004 without suppression is still active
+    au004_active = [
+        f for f in findings
+        if f.rule_id == "AU004" and not f.ignored
+    ]
+    assert len(au004_active) >= 1
+
+
+def test_suppress_cli_ignore_multiple_rules():
+    findings = scan(
+        [str(FIXTURES / "suppress_sample.py")],
+        ignore={"AU001", "AU002"},
+    )
+    au001 = [f for f in findings if f.rule_id == "AU001"]
+    au002 = [f for f in findings if f.rule_id == "AU002"]
+    assert all(f.ignored for f in au001)
+    assert all(f.ignored for f in au002)

{shellsafe-0.3.2 → shellsafe-0.3.4}/tests/unit/test_public_surface.py

@@ -4,7 +4,7 @@ import shellsafe
 
 
 def test_public_names_exist():
-    for name in ("run", "capture", "shx", "RAW", "CaptureResult", "__version__"):
+    for name in ("run", "capture", "shx", "plan", "RAW", "CaptureResult", "__version__"):
         assert hasattr(shellsafe, name), name
 
 
@@ -13,6 +13,7 @@ def test_all_is_exact():
         "run",
         "capture",
         "shx",
+        "plan",
         "RAW",
         "CaptureResult",
         "__version__",

shellsafe-0.3.2/src/shellsafe/_version.py

@@ -1 +0,0 @@
-__version__ = "0.3.2"