Merge pull request #83655 from tshortli/module-version-missing-warning-group

AST: Introduce a warning group for a versioned `#if canImport` diagnostic

Author: tshortli

include/swift/AST/DiagnosticGroups.def

@@ -53,6 +53,7 @@ GROUP(ImplementationOnlyDeprecated, "implementation-only-deprecated")
 GROUP(IsolatedConformances, "isolated-conformances")
 GROUP(MemberImportVisibility, "member-import-visibility")
 GROUP(MissingModuleOnKnownPaths, "missing-module-on-known-paths")
+GROUP(ModuleVersionMissing, "module-version-missing")
 GROUP(MultipleInheritance, "multiple-inheritance")
 GROUP(MutableGlobalVariable, "mutable-global-variable")
 GROUP(NominalTypes, "nominal-types")

include/swift/AST/DiagnosticsSema.def

@@ -1309,7 +1309,7 @@ REMARK(explicit_interface_build_skipped,none,
        "Skipped rebuilding module at %0 - up-to-date",
        (StringRef))
 
-WARNING(cannot_find_project_version,none,
+GROUPED_WARNING(cannot_find_module_version,ModuleVersionMissing,none,
         "cannot find user version number for%select{| Clang}1 module '%0';"
         " version number ignored", (StringRef, bool))
 

lib/AST/ASTContext.cpp

@@ -2617,7 +2617,7 @@ void ASTContext::addSucceededCanImportModule(
 
 bool ASTContext::canImportModuleImpl(
     ImportPath::Module ModuleName, SourceLoc loc, llvm::VersionTuple version,
-    bool underlyingVersion, bool isSourceCanImport,
+    bool isUnderlyingVersion, bool isSourceCanImport,
     llvm::VersionTuple &foundVersion,
     llvm::VersionTuple &foundUnderlyingClangVersion) const {
   SmallString<64> FullModuleName;
@@ -2629,16 +2629,16 @@ bool ASTContext::canImportModuleImpl(
     return false;
 
   auto missingVersion = [this, &loc, &ModuleName,
-                                 &underlyingVersion]() -> bool {
+                         &isUnderlyingVersion]() -> bool {
     // The module version could not be parsed from the preferred source for
-    // this query. Diagnose and return `true` to indicate that the unversioned module
-    // will satisfy the query.
+    // this query. Diagnose and return `true` to indicate that the unversioned
+    // module will satisfy the query.
     auto mID = ModuleName[0];
     auto diagLoc = mID.Loc;
     if (mID.Loc.isInvalid())
       diagLoc = loc;
-    Diags.diagnose(diagLoc, diag::cannot_find_project_version, mID.Item.str(),
-                   underlyingVersion);
+    Diags.diagnose(diagLoc, diag::cannot_find_module_version, mID.Item.str(),
+                   isUnderlyingVersion);
     return true;
   };
 
@@ -2650,9 +2650,9 @@ bool ASTContext::canImportModuleImpl(
     if (version.empty())
       return true;
 
-    const auto &foundComparisonVersion = underlyingVersion
-                                      ? Found->second.UnderlyingVersion
-                                      : Found->second.Version;
+    const auto &foundComparisonVersion = isUnderlyingVersion
+                                             ? Found->second.UnderlyingVersion
+                                             : Found->second.Version;
     if (!foundComparisonVersion.empty())
       return version <= foundComparisonVersion;
     else
@@ -2699,10 +2699,10 @@ bool ASTContext::canImportModuleImpl(
         bestUnderlyingVersionInfo = versionInfo;
     }
 
-    if (!underlyingVersion && !bestVersionInfo.isValid())
+    if (!isUnderlyingVersion && !bestVersionInfo.isValid())
       return false;
 
-    if (underlyingVersion && !bestUnderlyingVersionInfo.isValid())
+    if (isUnderlyingVersion && !bestUnderlyingVersionInfo.isValid())
       return false;
 
     foundVersion = bestVersionInfo.getVersion();
@@ -2751,7 +2751,8 @@ bool ASTContext::canImportModuleImpl(
   if (!lookupVersionedModule(versionInfo, underlyingVersionInfo))
     return false;
 
-  const auto &queryVersion = underlyingVersion ? underlyingVersionInfo : versionInfo;
+  const auto &queryVersion =
+      isUnderlyingVersion ? underlyingVersionInfo : versionInfo;
   if (queryVersion.getVersion().empty())
     return missingVersion();
 

userdocs/diagnostics/diagnostic-groups.md

@@ -33,6 +33,7 @@ Or upgrade all warnings except deprecated declaration to errors:
 - <doc:preconcurrency-import>
 - <doc:clang-declaration-import>
 - <doc:missing-module-on-known-paths>
+- <doc:module-version-missing>
 - <doc:strict-language-features>
 - <doc:strict-memory-safety>
 - <doc:unknown-warning-group>

userdocs/diagnostics/module-version-missing.md

@@ -0,0 +1,26 @@
+# Missing module version (ModuleVersionMissing)
+
+Warnings that indicate the compiler cannot resolve an `#if canImport(<ModuleName>, _version: <version>)` directive because the module found was not built with a `-user-module-version` flag.
+
+
+## Overview
+
+Developers may conditionalize which code is active in a source file based on the module version number of an imported dependency module, like this:
+
+```swift
+import Dependency
+
+#if canImport(Dependency, _version: 1.2)
+// Use declarations introduced in version 1.2 of Dependency
+#else
+// ...
+#endif
+```
+
+A dependency's module version must be established by passing the `-user-module-version` flag when compiling the sources of the dependency the module. If no `-user-module-version` flag was specified when the dependency module was built, then the compiler will warn that it cannot resolve the `#if canImport` directive:
+
+```
+warning: cannot find user version number for module 'Dependency'; version number ignored [#ModuleVersionMissing]
+```
+
+If this diagnostic is emitted, then the `#if canImport` directive implicitly evaluates true.