Sema: Reword diagnostics about potentially unavailable decls to improve clarity for authors of API libraries. When decls are diagnosed as potentially unavailable on an OS earlier than the deployment target, the message will now indicate that the issue would be faced by clients of the module.

Resolves rdar://93466875

Author: tshortli

include/swift/AST/DiagnosticsSema.def

@@ -5547,9 +5547,15 @@ ERROR(availability_decl_only_version_newer, none,
       "%0 is only available in %1 %2 or newer",
       (DeclName, StringRef, llvm::VersionTuple))
 
-WARNING(availability_decl_only_version_newer_warn, none,
-        "%0 is only available in %1 %2 or newer",
-        (DeclName, StringRef, llvm::VersionTuple))
+ERROR(availability_decl_only_version_newer_for_clients, none,
+      "%0 is only available in %1 %2 or newer; clients of %3 may have a lower"
+      " deployment target",
+      (DeclName, StringRef, llvm::VersionTuple, ModuleDecl *))
+
+WARNING(availability_decl_only_version_newer_for_clients_warn, none,
+        "%0 is only available in %1 %2 or newer; clients of %3 may have a lower"
+        " deployment target",
+        (DeclName, StringRef, llvm::VersionTuple, ModuleDecl *))
 
 ERROR(availability_opaque_types_only_version_newer, none,
       "'some' return types are only available in %0 %1 or newer",

lib/Sema/TypeCheckAvailability.cpp

@@ -1967,36 +1967,58 @@ void TypeChecker::checkConcurrencyAvailability(SourceRange ReferenceRange,
   }
 }
 
+/// Returns the diagnostic to emit for the potentially unavailable decl and sets
+/// \p IsError accordingly.
+static Diagnostic getPotentialUnavailabilityDiagnostic(
+    const ValueDecl *D, const DeclContext *ReferenceDC,
+    const UnavailabilityReason &Reason, bool WarnBeforeDeploymentTarget,
+    bool &IsError) {
+  ASTContext &Context = ReferenceDC->getASTContext();
+  auto Platform = prettyPlatformString(targetPlatform(Context.LangOpts));
+  auto Version = Reason.getRequiredOSVersionRange().getLowerEndpoint();
+
+  if (Version <= AvailabilityContext::forDeploymentTarget(Context)
+                     .getOSVersion()
+                     .getLowerEndpoint()) {
+    // The required OS version is at or before the deployment target so this
+    // diagnostic should indicate that the decl could be unavailable to clients
+    // of the module containing the reference.
+    IsError = !WarnBeforeDeploymentTarget;
+
+    return Diagnostic(
+        IsError ? diag::availability_decl_only_version_newer_for_clients
+                : diag::availability_decl_only_version_newer_for_clients_warn,
+        D->getName(), Platform, Version, ReferenceDC->getParentModule());
+  }
+
+  IsError = true;
+  return Diagnostic(diag::availability_decl_only_version_newer, D->getName(),
+                    Platform, Version);
+}
+
 bool TypeChecker::diagnosePotentialUnavailability(
     const ValueDecl *D, SourceRange ReferenceRange,
     const DeclContext *ReferenceDC,
     const UnavailabilityReason &Reason,
     bool WarnBeforeDeploymentTarget) {
   ASTContext &Context = ReferenceDC->getASTContext();
 
-  bool AsError = true;
   auto RequiredRange = Reason.getRequiredOSVersionRange();
+  bool IsError;
   {
-    if (WarnBeforeDeploymentTarget &&
-        !RequiredRange.isContainedIn(
-            AvailabilityContext::forDeploymentTarget(Context).getOSVersion()))
-      AsError = false;
-
     auto Diag = Context.Diags.diagnose(
         ReferenceRange.Start,
-        AsError ? diag::availability_decl_only_version_newer
-                : diag::availability_decl_only_version_newer_warn,
-        D->getName(), prettyPlatformString(targetPlatform(Context.LangOpts)),
-        Reason.getRequiredOSVersionRange().getLowerEndpoint());
+        getPotentialUnavailabilityDiagnostic(
+            D, ReferenceDC, Reason, WarnBeforeDeploymentTarget, IsError));
 
     // Direct a fixit to the error if an existing guard is nearly-correct
     if (fixAvailabilityByNarrowingNearbyVersionCheck(
             ReferenceRange, ReferenceDC, RequiredRange, Context, Diag))
-      return AsError;
+      return IsError;
   }
 
   fixAvailability(ReferenceRange, ReferenceDC, RequiredRange, Context);
-  return AsError;
+  return IsError;
 }
 
 void TypeChecker::diagnosePotentialAccessorUnavailability(