Add comprehensive tests and documentation for suppression feature

Co-authored-by: jackfirth <[email protected]>

Author: Copilot

main.scrbl

@@ -429,6 +429,38 @@ guide Resyntax's internal comment preservation system when the default behavior
  because such rules often touch only a small series of forms in a much larger definition context.}
 
 
+@subsection{Suppressing Specific Suggestions}
+
+@defform[(resyntax-suppress rule-id body ...+)]{
+ Suppresses the application of a specific @tech{refactoring rule} to the code in @racket[body]. The
+ @racket[rule-id] must be the name of a refactoring rule. This form is useful when a refactoring
+ suggestion makes sense generally, but is unhelpful in a specific context.
+
+ For example, suppose you have code that maintains visual symmetry by using similar comparisons with
+ zero:
+
+ @(racketblock
+   (and (= (- x y) 0)
+        (> (- x y) 0)
+        (< (- x y) 0)))
+
+ While Resyntax would normally suggest simplifying @racket[(> (- x y) 0)] to @racket[(> x y)], doing
+ so would break the visual pattern. You can suppress this specific suggestion while still allowing
+ other refactorings:
+
+ @(racketblock
+   (resyntax-suppress comparison-of-difference-and-zero-to-direct-comparison
+     (and (= (- x y) 0)
+          (> (- x y) 0)
+          (< (- x y) 0))))
+
+ The suppression applies to all code within the @racket[body] forms. Multiple expressions can be
+ suppressed together, and suppression works with nested forms.
+
+ Note that @racket[resyntax-suppress] must be @racket[require]d from @racket[resyntax/base] before
+ use.}
+
+
 @subsection{Resyntax's Default Rules}
 @defmodule[resyntax/default-recommendations]
 

test/suppression-comparison-test.rkt

@@ -0,0 +1,35 @@
+#lang resyntax/test
+
+
+require: resyntax/default-recommendations comparison-shortcuts
+
+
+header:
+------------------------------
+#lang racket/base
+(require resyntax/base)
+(define x 1)
+(define y 2)
+------------------------------
+
+
+no-change-test: "suppressing comparison rule prevents refactoring"
+------------------------------
+(resyntax-suppress comparison-of-difference-and-zero-to-direct-comparison
+  (> (- x y) 0))
+------------------------------
+
+
+test: "unsuppressed comparison is refactored"
+- (> (- x y) 0)
+- (> x y)
+
+
+no-change-test: "specific comparison in symmetrical context can be suppressed"
+------------------------------
+;; Example from the issue - maintaining visual symmetry
+(resyntax-suppress comparison-of-difference-and-zero-to-direct-comparison
+  (and (= (- x y) 0)
+       (> (- x y) 0)
+       (< (- x y) 0)))
+------------------------------

test/suppression-test.rkt

@@ -38,3 +38,31 @@ test: "suppression is specific to the rule name"
 (resyntax-suppress nested-or-to-flat-or
   (and 1 2 3))
 ------------------------------
+
+
+no-change-test: "multiple expressions can be suppressed in one form"
+------------------------------
+(resyntax-suppress nested-and-to-flat-and
+  (and 1 (and 2 3))
+  (and 4 (and 5 6)))
+------------------------------
+
+
+no-change-test: "suppression works with nested forms"
+------------------------------
+(resyntax-suppress nested-and-to-flat-and
+  (define x (and 1 (and 2 3)))
+  (define y (and 4 (and 5 6))))
+------------------------------
+
+
+test: "suppression outside a form doesn't affect it"
+------------------------------
+(resyntax-suppress nested-and-to-flat-and
+  (define x 1))
+(and 1 (and 2 3))
+==============================
+(resyntax-suppress nested-and-to-flat-and
+  (define x 1))
+(and 1 2 3)
+------------------------------