Merge pull request swiftlang#81034 from gottesmm/swift-snapshot-fixes-2

[swift-snapshot-tool] A few small fixes

Author: gottesmm

utils/swift_snapshot_tool/README.md

@@ -9,8 +9,8 @@ Used to list and bisect nightly snapshots off of swift.org.
 
 ```
 # xcrun swift run swift_snapshot_tool list
-[INFO] Starting to download snapshot information from github. 
-[INFO] Finished downloading snapshot information from github. 
+[INFO] Starting to download snapshot information from github.
+[INFO] Finished downloading snapshot information from github.
 0 swift-DEVELOPMENT-SNAPSHOT-2024-09-06-a
 1 swift-DEVELOPMENT-SNAPSHOT-2024-09-05-a
 2 swift-DEVELOPMENT-SNAPSHOT-2024-09-04-a
@@ -23,11 +23,46 @@ value is at. This allows for one to get a sense of the range of time in between
 two bisect numbers since one can look at the range in between them and how time
 varies.
 
+## Run
+
+```
+xcrun swift run swift_snapshot_tool run --script $SCRIPT_NAME \
+  --date YYYY-MM-DD [--invert] [--workspace $DIR_TO_DOWNLOAD_TOOLCHAINS]
+```
+
+run success is defined by `$SCRIPT_NAME` returning 0 as an exit code. All other
+exit codes are considered a failure.
+
+This command is meant to help one figure out where to start bisecting.
+
+Options:
+
+- workspace: This is the place where we will download toolchains to. Defaults to
+  `/tmp/swift_snapshot_tool_workspace_v1`. We suggest that you use an external
+  hard drive or a specified place so that one does not have to redownload
+  toolchains in between system restarts.
+
+- script: This is the script that should be run. We pass in the environment
+  variables `SWIFT_EXEC`, `SWIFT_FRONTEND`, and `SWIFT_LIBRARY_PATH` to the
+  script. If the script returns a zero exit code then the run is considered a
+  succeess. If the script returns a non-zero exit code, then the run is
+  considered a failure.
+
+- date: A date in the form YYYY-MM-DD. If a snapshot at date does not exist, we
+  choose the first snapshot before that date.
+
+- invert: This causes test.sh's result to be inverted. This allows one to bisect
+  backwards from a good state to a bad state. This is useful to determine when
+  an error was fixed.
+
+- branch: This controls the specific branch of snapshots that are downloaded. By
+  default uses development. Also supports the options 5.0 and 6.0.
+
 ## Bisect
 
 ```
-xcrun swift run swift_snapshot_tool bisect --script $SCRIPT_NAME --workspace $DIR_TO_DOWNLOAD_TOOLCHAINS \
-   --good-tag $OLDER_TAG_NAME_THAT_PASSES --bad-tag $NEWER_TAG_NAME_THAT_FAILS
+xcrun swift run swift_snapshot_tool bisect --script $SCRIPT_NAME --old-date YYYY_MM_DD \
+   [--new-date YYYY_MM_DD] [--workspace $DIR_TO_DOWNLOAD_TOOLCHAINS]
 ```
 
 bisect success is defined by `$SCRIPT_NAME` returning 0 as an exit code. All
@@ -36,18 +71,23 @@ other exit codes are considered a failure.
 Options:
 
 - workspace: This is the place where we will download toolchains to. Defaults to
-  `/tmp/swift_snapshot_tool_workspace_v1`
+  `/tmp/swift_snapshot_tool_workspace_v1`. We suggest that you use an external
+  hard drive or a specified place so that one does not have to redownload
+  toolchains in between system restarts.
 
 - script: This is the script that should be run. We pass in the environment
-  variables `SWIFT_EXEC` and `SWIFT_FRONTEND` to the subscript. If the script
-  returns a zero exit code then the run is considered a succeess. If the script
-  returns a non-zero exit code, then the run is considered a failure.
-
-- good_tag: This is the older tag and is assumed to succeed by returning a zero
-  exit code.
-
-- bad_tag: This is the newer tag and is assumed to fail by returning a non-zero
-  exit code.
+  variables `SWIFT_EXEC`, `SWIFT_FRONTEND`, `SWIFT_LIBRARY_PATH` to the
+  script. If the script returns a zero exit code then the run is considered a
+  succeess. If the script returns a non-zero exit code, then the run is
+  considered a failure.
+
+- old-date: Date in the form of YYYY-MM-DD. This is assumed to succeed by
+  returning a zero exit code. If a snapshot does not exist at this date, the
+  tool will choose the first snapshot before the date.
+
+- new-date: Date in the form of YYYY-MM-DD. This is assumed to fail by returning
+  a non-zero exit code. If a snapshot does not exist at this date, the tool will
+  choose the first snapshot before the date.
 
 - invert: This causes test.sh's result to be inverted. This allows one to bisect
   backwards from a good state to a bad state. This is useful to determine when

utils/swift_snapshot_tool/Sources/swift_snapshot_tool/bisect_toolchains.swift

@@ -17,8 +17,10 @@ struct BisectToolchains: AsyncParsableCommand {
   static let configuration = CommandConfiguration(
     commandName: "bisect",
     discussion: """
-      Bisects on exit status of attached script. Passes in name of swift as the
-      environment variables \(environmentVariables).
+      Bisects on swift snapshots downloaded from swift.org via an exit status of
+      a script. Script is passed paths into the downloaded snapshot via
+      environment variables and is expected to compile and or run swift programs
+      using the snapshot artifacts.
       """)
 
   @Flag var platform: Platform = .osx
@@ -34,13 +36,16 @@ struct BisectToolchains: AsyncParsableCommand {
 
   @Option(
     help: """
-      The script that should be run. It runs a specific swift compilation and
-      optionally program using the passed in environment variables
-      \(environmentVariables)
+      The script that should be run. It should run a specific swift compilation and
+      or program. Paths into the snapshots are passed in via the environment variables \(environmentVariables).
       """)
   var script: String
 
-  @Option(help: "Oldest Date. Expected to Pass. We use the first snapshot produced before the given date")
+  @Option(help:
+            """
+            Expected to Pass. We use the first snapshot produced before the
+            given date if a snapshot at this specific date does not exist
+            """)
   var oldDate: String
 
   var oldDateAsDate: Date {
@@ -54,9 +59,10 @@ struct BisectToolchains: AsyncParsableCommand {
   }
 
   @Option(help: """
-    Newest Date. Expected to fail. If not set, use newest snapshot. We use the
-    first snapshot after new date
-    """)
+            Expected to fail. If not set, defaults to use newest snapshot. If a
+            date is specified and a snapshot does not exist for that date, the
+            first snapshot before the specified date is used.
+            """)
   var newDate: String?
 
   var newDateAsDate: Date? {

utils/swift_snapshot_tool/Sources/swift_snapshot_tool/get_tags.swift

@@ -77,12 +77,10 @@ func getTagsFromSwiftRepo(branch: Branch, dryRun: Bool = false) async throws ->
   let allTags = try! decoder.decode([Tag].self, from: await data)
   log("[INFO] Finished downloading snapshot information from github.")
 
-  let snapshotTagPrefix = "swift-\(branch.rawValue.uppercased())"
-
   // Then filter the tags to just include the specific snapshot branch
   // prefix. Add the branch to an aggregate BranchTag.
   var filteredTags: [BranchTag] = allTags.filter {
-    $0.name.starts(with: snapshotTagPrefix)
+    $0.name.starts(with: branch.tagPrefix)
   }.map {
     BranchTag(tag: $0, branch: branch)
   }

utils/swift_snapshot_tool/Sources/swift_snapshot_tool/github_repository.swift

@@ -43,6 +43,16 @@ enum Platform: String, EnumerableFlag {
 
 enum Branch: String, EnumerableFlag {
   case development
-  case release50 = "5.0"
-  case release60 = "6.0"
+  case release_5_0 = "5.0"
+  case release_6_0 = "6.0"
+  case release_6_2 = "6.2"
+
+  var tagPrefix: String {
+    switch self {
+    case .development:
+       "swift-\(rawValue.uppercased())"
+    default:
+       "swift-\(rawValue.uppercased())-DEVELOPMENT"
+    }
+  }
 }

utils/swift_snapshot_tool/Sources/swift_snapshot_tool/list_snapshots.swift

@@ -14,7 +14,12 @@ import ArgumentParser
 
 struct ListSnapshots: AsyncParsableCommand {
   static let configuration = CommandConfiguration(
-    commandName: "list")
+    commandName: "list",
+    discussion: """
+      Downloads the current list of available snapshots from swift.org and
+      outputs the snapshots to stdout. Useful to see what snapshots are
+      available.
+      """)
 
   @Flag var platform: Platform = .osx
 

utils/swift_snapshot_tool/Sources/swift_snapshot_tool/run_toolchain.swift

@@ -17,8 +17,11 @@ struct RunToolchains: AsyncParsableCommand {
   static let configuration = CommandConfiguration(
     commandName: "run",
     discussion: """
-    Run a toolchain like bisect would. Passed the environment variables:
-    \(environmentVariables)
+      Run and determine success/failure of a script against a specified snapshot
+      like the bisect command would. Used to determine the start/end bisect
+      dates to pass to the bisect command. The script is passed paths into the
+      downloaded snapshot via environment variables and is expected to compile
+      and or run swift programs using the snapshot artifacts.
     """)
 
   @Flag var platform: Platform = .osx
@@ -34,8 +37,8 @@ struct RunToolchains: AsyncParsableCommand {
 
   @Option(
     help: """
-      The script that should be run. The environment variable
-      SWIFT_EXEC is used by the script to know where swift-frontend is
+      The script that should be run. It should run a specific swift compilation and
+      or program. Paths into the snapshots are passed in via the environment variables \(environmentVariables).
       """)
   var script: String