Fix unstable formatting with comments on optional parens

CHANGES.md

@@ -17,6 +17,10 @@
 
 <!-- Changes that affect Black's stable style -->
 
+- Fix unstable formatting when an inline comment sits on optional parentheses (for
+  example a parenthesized assert message or assignment RHS). Black no longer omits those
+  parentheses in a way that re-parents the comment and changes the split on a second
+  pass (#3701, #3706, #4384)
 - Fix crash when a standalone comment sits between tokens of a comprehension or lambda
   (#5144)
 - Fix crash when a comment-only `# fmt: off`/`# fmt: on` block is followed by a `with`

src/black/lines.py

@@ -1485,6 +1485,15 @@ def can_omit_invisible_parens(
     """
     line = rhs.body
 
+    # Don't omit optional parens when the opening paren carries an inline comment.
+    # Omitting them re-parents the comment onto a different leaf after the next
+    # parse, which can make the RHS splitter choose a different shape on each
+    # pass (unstable formatting / "different code on the second pass"). See
+    # issues #3701, #3706, and #4384.
+    if rhs.opening_bracket.type == token.LPAR and not rhs.opening_bracket.value:
+        if rhs.head.comments.get(id(rhs.opening_bracket)):
+            return False
+
     # We can't omit parens if doing so would result in a type: ignore comment
     # sharing a line with other comments, as that breaks type: ignore parsing.
     # Check if the opening bracket (last leaf of head) has comments that would merge

tests/data/cases/unstable_comment_on_optional_parens.py

@@ -0,0 +1,27 @@
+# Regression for https://github.com/psf/black/issues/3701
+# Inline comment on optional parentheses must not migrate across formatter passes.
+assert some_long_name, (  # long __________________________ comment
+        'long ___________________________________ string %s' % str(variable))
+
+
+# Related case from https://github.com/psf/black/issues/4384
+if 1:
+    takeoff_effective_friction_coefficient = (  # From Torenbeek, Eq. 5-76; an approximation
+            friction_coefficient +
+            0.72 * (CD_zero_lift / CL_max)
+    )
+
+# output
+
+# Regression for https://github.com/psf/black/issues/3701
+# Inline comment on optional parentheses must not migrate across formatter passes.
+assert some_long_name, (  # long __________________________ comment
+    "long ___________________________________ string %s" % str(variable)
+)
+
+
+# Related case from https://github.com/psf/black/issues/4384
+if 1:
+    takeoff_effective_friction_coefficient = (  # From Torenbeek, Eq. 5-76; an approximation
+        friction_coefficient + 0.72 * (CD_zero_lift / CL_max)
+    )