Merge branch 'main' into just-one-more-benchmark-suite

Author: natecook1000

.github/workflows/pull_request.yml

@@ -0,0 +1,79 @@
+name: Pull request
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+jobs:
+  tests:
+    name: Test
+    uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
+    with:
+      linux_exclude_swift_versions: '[{"swift_version": "5.9"}, {"swift_version": "5.10"}]'
+      enable_windows_checks: false
+      enable_macos_checks: false
+  soundness:
+    name: Soundness
+    uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
+    with:
+      license_header_check_project_name: "Swift.org"
+      unacceptable_language_check_enabled: false
+      format_check_enabled: false
+  bench:
+    name: Benchmark
+    runs-on: ubuntu-latest
+    env:
+      BUILD_CMD: swift build -c release
+      BENCH_CMD: .build/release/RegexBenchmark
+      BASELINE_FILE: benchmark-baseline
+      COMPARE_FILE: benchmark-pr
+      COMPARE_OUT_FILE: benchmark-results.txt
+    steps:
+      - name: Check out baseline branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+          path: base
+          fetch-depth: 0
+      - name: Build baseline branch
+        working-directory: base
+        run: |
+          set -euo pipefail
+          eval "$BUILD_CMD"
+      - name: Run baseline benchmark
+        working-directory: base
+        run: |
+          set -euo pipefail
+          eval "$BENCH_CMD --save $RUNNER_TEMP/$BASELINE_FILE"
+          test -s "$RUNNER_TEMP/$BASELINE_FILE" || { echo "Baseline not created at $BASELINE_FILE"; exit 1; }
+      - name: Check out PR branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          path: pr
+          fetch-depth: 0
+      - name: Build PR branch
+        working-directory: pr
+        run: |
+          set -euo pipefail
+          eval "$BUILD_CMD"
+      - name: Run PR benchmark
+        working-directory: pr
+        run: |
+          set -euo pipefail
+          eval "$BENCH_CMD --save $RUNNER_TEMP/$COMPARE_FILE"
+          test -s "$RUNNER_TEMP/$COMPARE_FILE" || { echo "Comparison not created at $COMPARE_FILE"; exit 1; }
+          eval "$BENCH_CMD --compare $RUNNER_TEMP/$BASELINE_FILE" | tee "$RUNNER_TEMP/$COMPARE_OUT_FILE"
+      - name: 📊 Compare benchmarks
+        working-directory: pr
+        run: |
+          set -euo pipefail
+          eval "$BENCH_CMD --load $RUNNER_TEMP/$COMPARE_FILE --compare $RUNNER_TEMP/$BASELINE_FILE --compare-compile-time $RUNNER_TEMP/$BASELINE_FILE" | tee "$RUNNER_TEMP/$COMPARE_OUT_FILE"
+      - name: Upload benchmark artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: |
+            ${{ runner.temp }}/${{ env.BASELINE_FILE }}
+            ${{ runner.temp }}/${{ env.COMPARE_FILE }}
+            ${{ runner.temp }}/${{ env.COMPARE_OUT_FILE }}

.gitignore

@@ -93,3 +93,6 @@ fastlane/test_output
 # https://github.com/johnno1962/injectionforxcode
 
 iOSInjectionProject/
+
+# DocC build folder
+*.docc-build

.license_header_template

@@ -0,0 +1,10 @@
+@@===----------------------------------------------------------------------===@@
+@@
+@@ This source file is part of the Swift.org open source project
+@@
+@@ Copyright (c) YEARS Apple Inc. and the Swift project authors
+@@ Licensed under Apache License v2.0 with Runtime Library Exception
+@@
+@@ See https://swift.org/LICENSE.txt for license information
+@@
+@@===----------------------------------------------------------------------===@@

.licenseignore

@@ -0,0 +1,25 @@
+.gitignore
+**/.gitignore
+.licenseignore
+.gitattributes
+.git-blame-ignore-revs
+.mailfilter
+.mailmap
+.spi.yml
+.swift-format
+.editorconfig
+.github/*
+.build
+*.py
+*.yml
+*.yaml
+*.cmake
+*.cmake.in
+Package.swift
+**/Package.swift
+Package@*.swift
+**/Package@*.swift
+Package.resolved
+**/Package.resolved
+.unacceptablelanguageignore
+ -a*/Snapshots/*

CMakeLists.txt

@@ -0,0 +1,30 @@
+# Programmer's Manual
+
+## Programming patterns
+
+### Engine quick checks and fast paths
+
+In the engine nomenclature, a quick-check results in a yes/no/maybe while a thorough check always results in a definite answer.
+
+The nature of quick checks and fast paths is that they bifurcate testing coverage. One easy way to prevent this in simple cases is to assert that a definite quick result matches the thorough result.
+
+One example of this pattern is matching against a builtin character class. The engine has a `_matchBuiltinCC`
+
+```swift
+  func _matchBuiltinCC(...) -> Input.Index? {
+    // Calls _quickMatchBuiltinCC, if that gives a definite result
+    // asserts that it is the same as the result of
+    // _thoroughMatchBuiltinCC and returns it. Otherwise returns the
+    // result of _thoroughMatchBuiltinCC
+  }
+
+  @inline(__always)
+  func _quickMatchBuiltinCC(...) -> QuickResult<Input.Index?>
+
+  @inline(never)
+  func _thoroughMatchBuiltinCC(...) -> Input.Index?
+```
+
+The thorough check is never inlined, as it is a lot of cold code. Note that quick and thorough functions should be pure, that is they shouldn't update processor state.
+
+

CODE_OF_CONDUCT.md

@@ -7,7 +7,23 @@ let availabilityDefinition = PackageDescription.SwiftSetting.unsafeFlags([
     "-Xfrontend",
     "-define-availability",
     "-Xfrontend",
-    "SwiftStdlib 5.7:macOS 9999, iOS 9999, watchOS 9999, tvOS 9999",
+    "SwiftStdlib 5.7:macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0",
+    "-Xfrontend",
+    "-define-availability",
+    "-Xfrontend",
+    "SwiftStdlib 5.8:macOS 13.3, iOS 16.4, watchOS 9.4, tvOS 16.4",
+    "-Xfrontend",
+    "-define-availability",
+    "-Xfrontend",
+    "SwiftStdlib 5.9:macOS 14.0, iOS 17.0, watchOS 10.0, tvOS 17.0",
+    "-Xfrontend",
+    "-define-availability",
+    "-Xfrontend",
+    "SwiftStdlib 5.10:macOS 9999, iOS 9999, watchOS 9999, tvOS 9999",
+    "-Xfrontend",
+    "-define-availability",
+    "-Xfrontend",
+    "SwiftStdlib 6.0:macOS 9999, iOS 9999, watchOS 9999, tvOS 9999",
 ])
 
 /// Swift settings for building a private stdlib-like module that is to be used
@@ -42,9 +58,10 @@ let package = Package(
         .executable(
             name: "VariadicsGenerator",
             targets: ["VariadicsGenerator"]),
+// Disable to work around rdar://126877024
         .executable(
-            name: "RegexBenchmark",
-            targets: ["RegexBenchmark"])
+          name: "RegexBenchmark",
+          targets: ["RegexBenchmark"])
     ],
     dependencies: [
         .package(url: "https://github.com/apple/swift-argument-parser", from: "1.0.0"),
@@ -75,18 +92,28 @@ let package = Package(
             name: "RegexBuilder",
             dependencies: ["_StringProcessing", "_RegexParser"],
             swiftSettings: publicStdlibSettings),
+        .target(name: "TestSupport",
+                swiftSettings: [availabilityDefinition]),
         .testTarget(
             name: "RegexTests",
-            dependencies: ["_StringProcessing"],
+            dependencies: ["_StringProcessing", "RegexBuilder", "TestSupport"],
             swiftSettings: [
-                .unsafeFlags(["-Xfrontend", "-disable-availability-checking"]),
+                availabilityDefinition
             ]),
         .testTarget(
             name: "RegexBuilderTests",
+            dependencies: ["_StringProcessing", "RegexBuilder", "TestSupport"],
+            swiftSettings: [
+                availabilityDefinition
+            ]),
+        .testTarget(
+            name: "DocumentationTests",
             dependencies: ["_StringProcessing", "RegexBuilder"],
             swiftSettings: [
-                .unsafeFlags(["-Xfrontend", "-disable-availability-checking"])
+                availabilityDefinition,
+                .unsafeFlags(["-enable-bare-slash-regex"]),
             ]),
+        
         // FIXME: Disabled due to rdar://94763190.
         // .testTarget(
         //     name: "Prototypes",
@@ -114,7 +141,8 @@ let package = Package(
                 .product(name: "ArgumentParser", package: "swift-argument-parser"),
                 "_RegexParser",
                 "_StringProcessing"
-            ]),
+            ],
+            swiftSettings: [availabilityDefinition]),
         .executableTarget(
             name: "RegexBenchmark",
             dependencies: [

CONTRIBUTING.md

@@ -8,7 +8,7 @@ See [Declarative String Processing Overview][decl-string]
 
 ## Requirements
 
-- [Swift Trunk Development Snapshot](https://www.swift.org/download/#snapshots) DEVELOPMENT-SNAPSHOT-2022-04-20 or later.
+- Currently tested with [Swift Trunk Development Snapshot](https://www.swift.org/download/#snapshots) DEVELOPMENT-SNAPSHOT-2025-09-14 or later.
 
 ## Trying it out
 
@@ -27,7 +27,7 @@ For example, in a `Package.swift` file's target declaration:
 
 ## Integration with Swift
 
-`_RegexParser` and `_StringProcessing` are specially integrated modules that are built as part of apple/swift.
+`_RegexParser` and `_StringProcessing` are specially integrated modules that are built as part of [apple/swift](https://github.com/apple/swift).
 
 Specifically, `_RegexParser` contains the parser for regular expression literals and is built both as part of the compiler and as a core library. `_CUnicode` and `_StringProcessing` are built together as a core library named `_StringProcessing`.
 
@@ -39,17 +39,14 @@ Specifically, `_RegexParser` contains the parser for regular expression literals
 
 ### Branching scheme
 
-#### Development branch
-
 The `main` branch is the branch for day-to-day development. Generally, you should create PRs against this branch.
 
-#### Swift integration branches
-
 Branches whose name starts with `swift/` are Swift integration branches similar to those in [apple/llvm-project](https://github.com/apple/llvm-project). For each branch, dropping the `swift/` prefix is the corresponding branch in [apple/swift](https://github.com/apple/swift).
 
+This package's `main` branch automatically integrates with Swift's `main` branch.
+
 | apple/swift branch  | apple/swift-experimental-string-processing branch     |
 | ------------------- | ----------------------------------------------------- |
-| main                | swift/main                                            |
 | release/5.7         | swift/release/5.7                                     |
 | ...                 | swift/...                                             |
 
@@ -59,11 +56,13 @@ A pair of corresponding branches are expected to build successfully together and
 
 To integrate the latest changes in apple/swift-experimental-string-processing to apple/swift, carefully follow the workflow: 
 
-- Create pull requests.
-  - Create a branch from a commit on `main` that you would like to integrate into `swift/main`.
-  - Create a pull request in apple/swift-experimental-string-processing from that branch to `swift/main`, e.g. "[Integration] main (<commit>) -> swift/main".
-  - If apple/swift needs to be modified to work with the latest `main` in apple/swift-experimental-string-processing, create a pull request in apple/swift.  **Note:** Since CI in apple/swift-experimental-string-processing has not yet been set up to run full toolchain tests, you should create a PR in apple/swift regardless; if the integartion does not require changing apple/swift, create a dummy PR in apple/swift by changing the README and just not merge it in the end.
-- Trigger CI.
+- Run package CI
+  - In the pull request, trigger package CI using
+```
+@swift-ci please test
+```
+- Run full Swift CI for any changes to public or SPI interfaces or the `_RegexParser` module.
+  - If apple/swift needs to be modified to work with the latest `main` in apple/swift-experimental-string-processing, create a pull request in apple/swift.  **Note:** Since CI in apple/swift-experimental-string-processing has not yet been set up to run full toolchain tests, you should create a PR in apple/swift regardless; if the integration does not require changing apple/swift, create a dummy PR in apple/swift by changing the README and close it in the end instead of merging.
   - In the apple/swift-experimental-string-processing pull request, trigger CI using the following command (replacing `<PR NUMBER>` with the apple/swift pull request number, if any):
     ```
     apple/swift#<PR NUMBER> # use this line only if there is an corresponding apple/swift PR
@@ -75,7 +74,9 @@ To integrate the latest changes in apple/swift-experimental-string-processing to
     @swift-ci please test
     ```
 - Merge when approved.
-  - Merge the pull request in apple/swift-experimental-string-processing as a **merge commit**.
+  - Merge the PR in apple/swift-experimental-string-processing:
+    - as a squash or rebase if against main (the development branch).
+    - as a merge commit if it's a merge from main to swift/release/x.y.
   - Merge the pull request in apple/swift (if any).
 
 ### Development notes