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,13 @@ 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 to clients of %1 in %2 %3 or newer",
+      (DeclName, ModuleDecl *, StringRef, llvm::VersionTuple))
+
+WARNING(availability_decl_only_version_newer_for_clients_warn, none,
+        "%0 is only available to clients of %1 in %2 %3 or newer",
+        (DeclName, ModuleDecl *, StringRef, llvm::VersionTuple))
 
 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();
+
+  const bool RequiredVersionIsDeploymentTargetOrLower =
+      Version <= AvailabilityContext::forDeploymentTarget(Context)
+                     .getOSVersion()
+                     .getLowerEndpoint();
+
+  if (RequiredVersionIsDeploymentTargetOrLower) {
+    IsError = !WarnBeforeDeploymentTarget;
+
+    return Diagnostic(
+        IsError ? diag::availability_decl_only_version_newer_for_clients
+                : diag::availability_decl_only_version_newer_for_clients_warn,
+        D->getName(), ReferenceDC->getParentModule(), Platform, Version);
+  }
+
+  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(