[clang] experimental-group (PR #233377)

[Utkarsh Saxena via cfe-commits]

https://github.com/usx95 created https://github.com/llvm/llvm-project/pull/233377

None

>From 74a89f691f10c09f0170d2120ef35dfae9127c62 Mon Sep 17 00:00:00 2001
From: Utkarsh Saxena <usx at google.com>
Date: Wed, 14 Oct 2026 13:18:24 +0000
Subject: [PATCH] experimental-group

---
 clang/docs/LifetimeSafety.md                  | 10 ++++++++--
 clang/docs/ReleaseNotes.md                    | 10 ++++++++++
 clang/include/clang/Basic/DiagnosticGroups.td | 20 ++++++++++++++-----
 .../LifetimeSafety/annotation-suggestions.cpp |  6 +++---
 .../Sema/LifetimeSafety/invalidations.cpp     |  2 +-
 5 files changed, 37 insertions(+), 11 deletions(-)

diff --git a/clang/docs/LifetimeSafety.md b/clang/docs/LifetimeSafety.md
index 2785d2c80ccb18..ea2364deaee618 100644
--- a/clang/docs/LifetimeSafety.md
+++ b/clang/docs/LifetimeSafety.md
@@ -387,6 +387,8 @@ iterators, pointers and references to its elements.
 
 :::{note}
 Invalidation checking is highly experimental and may produce false positives.
+It is not enabled by `-Wlifetime-safety`; use
+`-Wlifetime-safety-experimental-invalidation` or `-Wlifetime-safety-experimental`.
 :::
 
 ````{list-table}
@@ -500,12 +502,11 @@ enables only the high-confidence subset of these checks.
     - `-Wlifetime-safety-return-stack-addr`: Warns when a function returns a pointer or reference to one of its local stack variables.
     - `-Wlifetime-safety-dangling-field`: Warns when a class field is assigned a pointer to a temporary or stack variable whose lifetime is shorter than the class instance.
 
-  - `-Wlifetime-safety-strict`: Enables stricter and experimental checks. These may produce false positives in code that uses move semantics heavily, as the analysis might conservatively assume a use-after-free even if ownership was transferred.
+  - `-Wlifetime-safety-strict`: Enables stricter checks. These may produce false positives in code that uses move semantics heavily, as the analysis might conservatively assume a use-after-free even if ownership was transferred.
 
     - `-Wlifetime-safety-use-after-scope-moved`: Same as `-Wlifetime-safety-use-after-scope` but for cases where the variable may have been moved from before its destruction.
     - `-Wlifetime-safety-return-stack-addr-moved`: Same as `-Wlifetime-safety-return-stack-addr` but for cases where the variable may have been moved from.
     - `-Wlifetime-safety-dangling-field-moved`: Same as `-Wlifetime-safety-dangling-field` but for cases where the variable may have been moved from.
-    - `-Wlifetime-safety-invalidation`: Warns when a pointer, reference, iterator or view is used after an operation that may invalidate it, such as container mutation or explicit destruction (e.g., `std::unique_ptr::reset`, `std::destroy_at`) (Experimental).
 
 - `-Wlifetime-safety-suggestions`: Enables suggestions to add `[[clang::lifetimebound]]` to function parameters and `this` parameters.
 
@@ -519,6 +520,11 @@ enables only the high-confidence subset of these checks.
   - `-Wlifetime-safety-noescape`: Warns when a parameter marked with `[[clang::noescape]]` escapes the function.
   - `-Wlifetime-safety-lifetimebound-violation`: Warns when the analysis cannot verify that the return value can be lifetime bound to a parameter marked with `[[clang::lifetimebound]]`.
 
+- `-Wlifetime-safety-experimental`: Enables experimental checks. These may have known false positives and their behavior may change. They are not enabled by `-Wlifetime-safety-all`.
+
+  - `-Wlifetime-safety-experimental-invalidation`: Warns when a pointer, reference, iterator or view is used after an operation that may invalidate it, such as container mutation or explicit destruction (e.g., `std::unique_ptr::reset`, `std::destroy_at`).
+  - `-Wlifetime-safety-experimental-field-origin-escape`: Warns when a member function returns a value derived from a pointer, reference, or view field rather than from `*this` (e.g., `Span::data()`). Owned pointer fields (e.g., `Vector::data()`) are also reported; mark such methods `[[clang::lifetimebound]]` to silence the warning.
+
 ## Limitations
 
 ### Move Semantics
diff --git a/clang/docs/ReleaseNotes.md b/clang/docs/ReleaseNotes.md
index 7d6347414cc5c8..1898d3dcd44865 100644
--- a/clang/docs/ReleaseNotes.md
+++ b/clang/docs/ReleaseNotes.md
@@ -516,6 +516,16 @@ features cannot lower the translation-unit ABI level;
   };
   ```
 
+- Added `-Wlifetime-safety-experimental` to group experimental lifetime safety
+  warnings. It is not part of `-Wlifetime-safety-all`. It contains:
+
+  - `-Wlifetime-safety-experimental-invalidation`, renamed from
+    `-Wlifetime-safety-invalidation` and no longer enabled by
+    `-Wlifetime-safety` or `-Wlifetime-safety-strict`.
+  - `-Wlifetime-safety-experimental-field-origin-escape`, which warns when a
+    member function returns a value derived from a pointer, reference, or view
+    field rather than from `*this`.
+
 - Lifetime safety analysis is now enabled for C by default. The `-fexperimental-lifetime-safety-c`
   flag is renamed to `-flifetime-safety-c`. Use `-fno-lifetime-safety-c` to disable it.
 
diff --git a/clang/include/clang/Basic/DiagnosticGroups.td b/clang/include/clang/Basic/DiagnosticGroups.td
index b6c7ff7276260f..b3bb2fb1b53fdc 100644
--- a/clang/include/clang/Basic/DiagnosticGroups.td
+++ b/clang/include/clang/Basic/DiagnosticGroups.td
@@ -634,9 +634,10 @@ This may contain false-positives, e.g. when the borrowed storage is potentially
   }];
 }
 
-def LifetimeSafetyInvalidation : DiagGroup<"lifetime-safety-invalidation"> {
+def LifetimeSafetyInvalidation
+    : DiagGroup<"lifetime-safety-experimental-invalidation"> {
   code Documentation = [{
-Warning to detect invalidation of references.
+Experimental. Warning to detect invalidation of references.
   }];
 }
 
@@ -681,8 +682,7 @@ def LifetimeSafetyStrict : DiagGroup<"lifetime-safety-strict",
                                     LifetimeSafetyDanglingFieldMoved,
                                     LifetimeSafetyDanglingFieldLambdaCapture,
                                     LifetimeSafetyDanglingGlobalMoved,
-                                    LifetimeSafetyDanglingGlobalInMain,
-                                    LifetimeSafetyInvalidation]>;
+                                    LifetimeSafetyDanglingGlobalInMain]>;
 
 def LifetimeSafety : DiagGroup<"lifetime-safety",
                                [LifetimeSafetyPermissive, LifetimeSafetyStrict]> {
@@ -745,7 +745,7 @@ Validates correct usage and adherence to lifetime safety annotations like [[clan
 }
 
 def LifetimeSafetyFieldOriginEscape
-    : DiagGroup<"experimental-lifetime-safety-field-origin-escape"> {
+    : DiagGroup<"lifetime-safety-experimental-field-origin-escape"> {
   code Documentation = [{
 Experimental. Detects member functions returning a value derived from a
 pointer, reference, or view field rather than from ``*this``. May report owned
@@ -754,6 +754,16 @@ method ``[[clang::lifetimebound]]``.
   }];
 }
 
+def LifetimeSafetyExperimental
+    : DiagGroup<"lifetime-safety-experimental",
+                [LifetimeSafetyInvalidation,
+                 LifetimeSafetyFieldOriginEscape]> {
+  code Documentation = [{
+Experimental lifetime safety warnings. These may have known false positives and
+their behavior may change. Not enabled by -Wlifetime-safety-all.
+  }];
+}
+
 def LifetimeSafetyAll : DiagGroup<"lifetime-safety-all",
                                   [LifetimeSafety,
                                   LifetimeSafetySuggestions,
diff --git a/clang/test/Sema/LifetimeSafety/annotation-suggestions.cpp b/clang/test/Sema/LifetimeSafety/annotation-suggestions.cpp
index 34f3ad4f45de1a..5056a9b624dccd 100644
--- a/clang/test/Sema/LifetimeSafety/annotation-suggestions.cpp
+++ b/clang/test/Sema/LifetimeSafety/annotation-suggestions.cpp
@@ -1,8 +1,8 @@
 // RUN: rm -rf %t
 // RUN: split-file %s %t
-// RUN: %clang_cc1 -fsyntax-only -flifetime-safety-inference -fexperimental-lifetime-safety-tu-analysis -Wlifetime-safety-suggestions -Wlifetime-safety -Wlifetime-safety-annotation-placement -Wexperimental-lifetime-safety-field-origin-escape -Wno-dangling -I%t -I%S -verify %t/test_source.cpp
-// RUN: %clang_cc1 -fsyntax-only -std=c++23 -flifetime-safety-inference -fexperimental-lifetime-safety-tu-analysis -Wlifetime-safety-suggestions -Wlifetime-safety -Wexperimental-lifetime-safety-field-origin-escape -Wno-dangling -I%t -I%S -verify %t/test_source.cpp
-// RUN: %clang_cc1 -flifetime-safety-inference -fexperimental-lifetime-safety-tu-analysis -Wlifetime-safety-suggestions -Wlifetime-safety -Wexperimental-lifetime-safety-field-origin-escape -Wno-dangling -I%t -I%S -fixit %t/test_source.cpp
+// RUN: %clang_cc1 -fsyntax-only -flifetime-safety-inference -fexperimental-lifetime-safety-tu-analysis -Wlifetime-safety-suggestions -Wlifetime-safety -Wlifetime-safety-annotation-placement -Wlifetime-safety-experimental-field-origin-escape -Wno-dangling -I%t -I%S -verify %t/test_source.cpp
+// RUN: %clang_cc1 -fsyntax-only -std=c++23 -flifetime-safety-inference -fexperimental-lifetime-safety-tu-analysis -Wlifetime-safety-suggestions -Wlifetime-safety -Wlifetime-safety-experimental-field-origin-escape -Wno-dangling -I%t -I%S -verify %t/test_source.cpp
+// RUN: %clang_cc1 -flifetime-safety-inference -fexperimental-lifetime-safety-tu-analysis -Wlifetime-safety-suggestions -Wlifetime-safety -Wlifetime-safety-experimental-field-origin-escape -Wno-dangling -I%t -I%S -fixit %t/test_source.cpp
 // RUN: %clang_cc1 -fsyntax-only -flifetime-safety-inference -fexperimental-lifetime-safety-tu-analysis -Wlifetime-safety-suggestions -Wno-dangling -I%t -I%S -Werror=lifetime-safety-suggestions %t/test_source.cpp
 
 View definition_before_header(View a);
diff --git a/clang/test/Sema/LifetimeSafety/invalidations.cpp b/clang/test/Sema/LifetimeSafety/invalidations.cpp
index a7c62852c69892..f96e8259b64ebc 100644
--- a/clang/test/Sema/LifetimeSafety/invalidations.cpp
+++ b/clang/test/Sema/LifetimeSafety/invalidations.cpp
@@ -1,4 +1,4 @@
-// RUN: %clang_cc1 -fsyntax-only -Wlifetime-safety -Wno-dangling -verify %s
+// RUN: %clang_cc1 -fsyntax-only -Wlifetime-safety -Wlifetime-safety-experimental-invalidation -Wno-dangling -verify %s
 
 #include "Inputs/lifetime-analysis.h"