Allow sources anywhere in ./Sources when only one target is present (#6294)

After getting some feedback about the added `path` argument for executable
packages generated with `swift package init` (#6144), this change allows a
target's sources to occupy the entire "predefined sources directory" (e.g.
`Sources`, `Tests`, or `Plugins`) when there is only one target of a specific
kind occupying one of those directories in the package. All package types can
benefit from this.

For example, if there is only one library target and one test target, one can
put sources directly in `./Sources` and `./Tests`. Adding another library means
that one has to put the sources for TargetA in `./Sources/TargetA` and the
sources for TargetB in `./Sources/TargetB`, and so on.

When there is more than one target of a type in a package, the existing
requirements for target sources still apply.

This change should be compatible with existing layouts as well. If there is
only a single target in a package, then sources can of course continue to exist
exclusively in `./Sources/<target>`, or `./Tests/<testTarget>`, etc.

Amend the `executable` and `tool` template's generated manifest to not include
the `path` argument anymore as it is no longer needed.

With this change, the `library` template type can also put its sources and tests
directly in the `./Sources` and `./Tests` directories respectively.

All of the above only takes place when the tools version is set to 5.9 or
higher in the manifest.

rdar://106829666

Author: bitjammer

CHANGELOG.md

@@ -24,6 +24,10 @@ Swift Next
 Swift 5.9
 -----------
 
+* [#6294]
+
+  When a package contains a single target, sources may be distributed anywhere within the `./Sources` directory. If sources are placed in a subdirectory under `./Sources/<target>`, or there is more than one target, the existing expectation for sources apply.
+
 * [#6114]
 
   Added a new `allowNetworkConnections(scope:reason:)` for giving a command plugin permissions to access the network. Permissions can be scoped to Unix domain sockets in general or specifically for Docker, as well as local or remote IP connections which can be limited by port. For non-interactive use cases, there is also a `--allow-network-connections` commandline flag to allow network connections for a particular scope.

Sources/PackageLoading/Diagnostics.swift

@@ -15,8 +15,14 @@ import PackageModel
 import TSCBasic
 
 extension Basics.Diagnostic {
-    static func targetHasNoSources(targetPath: String, target: String) -> Self {
-        .warning("Source files for target \(target) should be located under \(targetPath)")
+    static func targetHasNoSources(name: String, type: TargetDescription.TargetType, shouldSuggestRelaxedSourceDir: Bool) -> Self {
+        let folderName = PackageBuilder.suggestedPredefinedSourceDirectory(type: type)
+        var clauses = ["Source files for target \(name) should be located under '\(folderName)/\(name)'"]
+        if shouldSuggestRelaxedSourceDir {
+            clauses.append("'\(folderName)'")
+        }
+        clauses.append("or a custom sources path can be set with the 'path' property in Package.swift")
+        return .warning(clauses.joined(separator: ", "))
     }
 
     static func targetNameHasIncorrectCase(target: String) -> Self {

Sources/PackageLoading/PackageBuilder.swift

@@ -30,7 +30,7 @@ public enum ModuleError: Swift.Error {
     case duplicateModule(String, [String])
 
     /// The referenced target could not be found.
-    case moduleNotFound(String, TargetDescription.TargetType)
+    case moduleNotFound(String, TargetDescription.TargetType, shouldSuggestRelaxedSourceDir: Bool)
 
     /// The artifact for the binary target could not be found.
     case artifactNotFound(targetName: String, expectedArtifactName: String)
@@ -87,9 +87,14 @@ extension ModuleError: CustomStringConvertible {
         case .duplicateModule(let name, let packages):
             let packages = packages.joined(separator: "', '")
             return "multiple targets named '\(name)' in: '\(packages)'; consider using the `moduleAliases` parameter in manifest to provide unique names"
-        case .moduleNotFound(let target, let type):
+        case .moduleNotFound(let target, let type, let shouldSuggestRelaxedSourceDir):
             let folderName = (type == .test) ? "Tests" : (type == .plugin) ? "Plugins" : "Sources"
-            return "Source files for target \(target) should be located under '\(folderName)/\(target)', or a custom sources path can be set with the 'path' property in Package.swift"
+            var clauses = ["Source files for target \(target) should be located under '\(folderName)/\(target)'"]
+            if shouldSuggestRelaxedSourceDir {
+                clauses.append("'\(folderName)'")
+            }
+            clauses.append("or a custom sources path can be set with the 'path' property in Package.swift")
+            return clauses.joined(separator: ", ")
         case .artifactNotFound(let targetName, let expectedArtifactName):
             return "binary target '\(targetName)' could not be mapped to an artifact with expected name '\(expectedArtifactName)'"
         case .invalidModuleAlias(let originalName, let newName):
@@ -526,12 +531,23 @@ public final class PackageBuilder {
                 return path
             }
 
+            let commonTargetsOfSimilarType = self.manifest.targetsWithCommonSourceRoot(type: target.type).count
+            // If there is only one target defined, it may be allowed to occupy the
+            // entire predefined target directory.
+            if self.manifest.toolsVersion >= .v5_9 {
+                if commonTargetsOfSimilarType == 1 {
+                    return predefinedDir.path
+                }
+            }
+
             // Otherwise, if the path "exists" then the case in manifest differs from the case on the file system.
             if fileSystem.isDirectory(path) {
                 self.observabilityScope.emit(.targetNameHasIncorrectCase(target: target.name))
                 return path
             }
-            throw ModuleError.moduleNotFound(target.name, target.type)
+            throw ModuleError.moduleNotFound(target.name,
+                                             target.type,
+                                             shouldSuggestRelaxedSourceDir: self.manifest.shouldSuggestRelaxedSourceDir(type: target.type))
         }
 
         // Create potential targets.
@@ -568,7 +584,10 @@ public final class PackageBuilder {
         let missingModuleNames = allVisibleModuleNames.subtracting(potentialModulesName)
         if let missingModuleName = missingModuleNames.first {
             let type = potentialModules.first(where: { $0.name == missingModuleName })?.type ?? .regular
-            throw ModuleError.moduleNotFound(missingModuleName, type)
+            throw ModuleError.moduleNotFound(missingModuleName,
+              type,
+              shouldSuggestRelaxedSourceDir: self.manifest.shouldSuggestRelaxedSourceDir(type: type)
+            )
         }
 
         let products = Dictionary(manifest.products.map({ ($0.name, $0) }), uniquingKeysWith: { $1 })
@@ -707,7 +726,9 @@ public final class PackageBuilder {
                 targets[createdTarget.name] = createdTarget
             } else {
                 emptyModules.insert(potentialModule.name)
-                self.observabilityScope.emit(.targetHasNoSources(targetPath: potentialModule.path.pathString, target: potentialModule.name))
+                self.observabilityScope.emit(.targetHasNoSources(name: potentialModule.name,
+                                                                 type: potentialModule.type,
+                                                                 shouldSuggestRelaxedSourceDir: manifest.shouldSuggestRelaxedSourceDir(type: potentialModule.type)))
             }
         }
 
@@ -1391,6 +1412,19 @@ public final class PackageBuilder {
         }
         return true
     }
+
+    /// Returns the first suggested predefined source directory for a given target type.
+    public static func suggestedPredefinedSourceDirectory(type: TargetDescription.TargetType) -> String {
+        // These are static constants, safe to access by index; the first choice is preferred.
+        switch type {
+        case .test:
+            return predefinedTestDirectories[0]
+        case .plugin:
+            return predefinedPluginDirectories[0]
+        default:
+            return predefinedSourceDirectories[0]
+        }
+    }
 }
 
 extension PackageBuilder {

Sources/PackageModel/Manifest/Manifest.swift

@@ -454,6 +454,26 @@ public final class Manifest: Sendable {
             return false
         }
     }
+
+    /// Returns a list of target descriptions whose root source directory is the same as that for the given type.
+    public func targetsWithCommonSourceRoot(type: TargetDescription.TargetType) -> [TargetDescription] {
+        switch type {
+        case .test:
+            return targets.filter { $0.type == .test }
+        case .plugin:
+            return targets.filter { $0.type == .plugin }
+        default:
+            return targets.filter { $0.type != .test && $0.type != .plugin }
+        }
+    }
+
+    /// Returns true if the tools version is >= 5.9 and the number of targets with a common source root is 1.
+    public func shouldSuggestRelaxedSourceDir(type: TargetDescription.TargetType) -> Bool {
+        guard toolsVersion >= .v5_9 else {
+            return false
+        }
+        return targetsWithCommonSourceRoot(type: type).count == 1
+    }
 }
 
 extension Manifest: Hashable {

Sources/Workspace/InitPackage.swift

@@ -257,8 +257,7 @@ public final class InitPackage {
                 if packageType == .executable {
                     param += """
                             .executableTarget(
-                                name: "\(pkgname)",
-                                path: "Sources"),
+                                name: "\(pkgname)")
                         ]
                     """
                 } else if packageType == .tool {
@@ -267,8 +266,7 @@ public final class InitPackage {
                                 name: "\(pkgname)",
                                 dependencies: [
                                     .product(name: "ArgumentParser", package: "swift-argument-parser"),
-                                ],
-                                path: "Sources"),
+                                ]),
                         ]
                     """
                 } else if packageType == .macro {
@@ -364,9 +362,13 @@ public final class InitPackage {
         progressReporter?("Creating \(sources.relative(to: destinationPath))/")
         try makeDirectories(sources)
 
-        let moduleDir = packageType == .executable || packageType == .tool
-          ? sources
-          : sources.appending("\(pkgname)")
+        let moduleDir: AbsolutePath
+        switch packageType {
+        case .executable, .tool:
+            moduleDir = sources
+        default:
+            moduleDir = sources.appending("\(pkgname)")
+        }
         try makeDirectories(moduleDir)
 
         let sourceFileName: String

Tests/PackageGraphTests/PackageGraphTests.swift

@@ -516,7 +516,7 @@ class PackageGraphTests: XCTestCase {
 
         testDiagnostics(observability.diagnostics) { result in
             result.check(
-                diagnostic: "Source files for target Bar should be located under \(Bar.appending(components: "Sources", "Bar"))",
+                diagnostic: .contains("Source files for target Bar should be located under 'Sources/Bar'"),
                 severity: .warning
             )
             result.check(