Docs (#4)

Author: NSFatalError

.github/workflows/pull-request.yml

@@ -1,25 +1,116 @@
 name: Pull request
 on: pull_request
 
+env:
+  XCODE_VERSION: "16.3"
+
 jobs:
-  pull-request:
+  prepare:
     runs-on: macos-15
-
+    outputs:
+      platforms: ${{ steps.platforms.outputs.platforms }}
+      scheme: ${{ steps.scheme.outputs.scheme }}
     steps:
     - uses: actions/checkout@v4
+    - name: Setup Xcode
+      run: sudo xcode-select -s /Applications/Xcode_$XCODE_VERSION.app
 
-    - name: Setup
+    - name: Setup mise
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       run: |
         curl https://mise.run | sh
         mise install
-
-    - name: Lint
+    - name: Run linters
       run: mise lint
 
-    - name: Build
+    - name: Extract platforms
+      id: platforms
+      run: |
+        platforms=$(swift package dump-package | jq -r '[.platforms[].platformName] | unique | @json')
+        echo "Platforms: $platforms"
+        echo "platforms=$platforms" >> $GITHUB_OUTPUT
+
+    - name: Extract scheme
+      id: scheme
+      run: |
+        repo=$(basename $GITHUB_REPOSITORY)
+        schemes=$(xcodebuild -list)
+        echo "$schemes"
+
+        if echo "$schemes" | grep -q "$repo-Package"; then
+          scheme="$repo-Package"
+        elif echo "$schemes" | grep -q "$repo"; then
+          scheme="$repo"
+        else
+          echo "Unable to select a scheme"
+          exit 1
+        fi
+
+        echo "Selected scheme: $scheme"
+        echo "scheme=$scheme" >> $GITHUB_OUTPUT
+
+  build-and-test:
+    needs: prepare
+    runs-on: macos-15
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: ${{ fromJSON(needs.prepare.outputs.platforms) }}
+    steps:
+    - uses: actions/checkout@v4
+    - name: Setup Xcode
+      run: sudo xcode-select -s /Applications/Xcode_$XCODE_VERSION.app
+
+    - name: Map destinations
+      if: ${{ matrix.platform != 'macos' }}
+      id: destination
+      run: |
+        case "${{ matrix.platform }}" in
+          ios)
+            destination="platform=iOS Simulator,name=iPhone 16 Pro Max,OS=latest"
+            ;;
+          maccatalyst)
+            destination="platform=macOS,variant=Mac Catalyst"
+            ;;
+          tvos)
+            destination="platform=tvOS Simulator,name=Apple TV 4K (3rd generation),OS=latest"
+            ;;
+          visionos)
+            destination="platform=visionOS Simulator,name=Apple Vision Pro,OS=latest"
+            ;;
+          watchos)
+            destination="platform=watchOS Simulator,name=Apple Watch Series 10 (46mm),OS=latest"
+            ;;
+          *)
+            echo "Unknown platform: ${{ matrix.platform }}"
+            exit 1
+            ;;
+        esac
+        echo "destination=$destination" >> $GITHUB_OUTPUT
+
+    - name: Build (SPM)
+      if: ${{ matrix.platform == 'macos' }}
       run: swift build
+    - name: Build (Xcode)
+      if: ${{ matrix.platform != 'macos' }}
+      run: |
+        set -o pipefail
+        xcodebuild build \
+          -scheme ${{ needs.prepare.outputs.scheme }} \
+          -destination "${{ steps.destination.outputs.destination }}" | \
+          xcbeautify --renderer github-actions
 
-    - name: Test
-      run: swift test
+    - name: Test (SPM)
+      if: ${{ matrix.platform == 'macos' }}
+      run: |
+        set -o pipefail
+        swift test | xcbeautify --renderer github-actions
+    - name: Test (Xcode)
+      if: ${{ matrix.platform != 'macos' }}
+      run: |
+        set -o pipefail
+        xcodebuild test \
+          -scheme ${{ needs.prepare.outputs.scheme }} \
+          -destination "${{ steps.destination.outputs.destination }}" | \
+          xcbeautify --renderer github-actions

.github/workflows/release.yml

@@ -1,21 +1,43 @@
 name: Release
-
 on:
   push:
     tags:
       - '*'
 
+env:
+  XCODE_VERSION: "16.3"
+
 jobs:
   release:
-    runs-on: ubuntu-latest
-
+    runs-on: macos-15
     steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Xcode
+        run: sudo xcode-select -s /Applications/Xcode_$XCODE_VERSION.app
+
+      - name: Verify changes
+        run: |
+          current_tag=${GITHUB_REF#refs/tags/}
+          previous_tag=$(git tag --sort=-v:refname | head -n 2 | tail -n 1)
+
+          current_major=$(echo "$current_tag" | cut -d '.' -f 1)
+          previous_major=$(echo "$previous_tag" | cut -d '.' -f 1)
+          echo "Comparing $current_tag with $previous_tag..."
+
+          if [ "$current_major" -gt "$previous_major" ]; then
+            swift package diagnose-api-breaking-changes "$previous_tag" || true
+          else
+            swift package diagnose-api-breaking-changes "$previous_tag"
+          fi
+
       - name: Draft release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          TAG_NAME=${GITHUB_REF#refs/tags/}
-          gh release create "$TAG_NAME" \
+          current_tag=${GITHUB_REF#refs/tags/}
+          gh release create "$current_tag" \
             --repo="$GITHUB_REPOSITORY" \
             --generate-notes \
-            --draft
+            --draft

.swiftlint.yml

@@ -166,6 +166,9 @@ file_length:
 identifier_name:
     excluded: [id, x, y, z]
 
+line_length:
+    ignores_comments: true
+
 nesting:
     type_level: 2
 
@@ -192,4 +195,4 @@ custom_rules:
     empty_line_after_type_declaration:
         name: "Empty line after type declaration"
         message: "Type declaration should start with an empty line."
-        regex: "( |^)(actor|class|struct|enum|protocol|extension) (?!var)[^\\{]*? \\{(?!\\n*\\}) *\\n? *\\S"
+        regex: "( |^)(actor|class|struct|enum|protocol|extension) (?!var)[^\\{]*? \\{(?!\\s*\\}) *\\n? *\\S"

Package.resolved

@@ -1,17 +1,17 @@
-// swift-tools-version: 6.0
+// swift-tools-version: 6.1
 // The swift-tools-version declares the minimum version of Swift required to build this package.
 
 import PackageDescription
 
 let package = Package(
     name: "PrincipleMacros",
     platforms: [
-        .macOS(.v13),
-        .macCatalyst(.v16),
-        .iOS(.v16),
-        .tvOS(.v16),
-        .watchOS(.v9),
-        .visionOS(.v1)
+        .macOS(.v15),
+        .macCatalyst(.v18),
+        .iOS(.v18),
+        .tvOS(.v18),
+        .watchOS(.v11),
+        .visionOS(.v2)
     ],
     products: [
         .library(
@@ -22,7 +22,7 @@ let package = Package(
     dependencies: [
         .package(
             url: "https://github.com/NSFatalError/Principle",
-            from: "0.0.1"
+            from: "1.0.0"
         ),
         .package(
             url: "https://github.com/swiftlang/swift-syntax",

Package.swift

@@ -1 +1,19 @@
 # PrincipleMacros
+
+![Swift](https://img.shields.io/badge/Swift-6.0-EF5239?logo=swift&labelColor=white)
+
+Essential tools that extend the capabilities of `SwiftSyntax`, simplifying the implementation of custom macros.
+
+> [!WARNING]
+> This package is considered an implementation detail of some of my other open-source projects.
+> While it follows semantic versioning rules and has decent test coverage, it is currently undocumented, 
+> and future releases may introduce multiple breaking changes. Use it at your own discretion.
+
+## Installation
+
+```swift
+.package(
+    url: "https://github.com/NSFatalError/PrincipleMacros",
+    from: "1.0.0"
+)
+```

README.md

@@ -25,16 +25,21 @@ public struct SwitchExprBuilder: ExprBuilder {
     }
 
     public func build() -> SwitchExprSyntax {
-        SwitchExprSyntax(subject: subject, cases: switchCases())
+        SwitchExprSyntax(
+            subject: subject.withLeadingSpace.withTrailingSpace,
+            leftBrace: .leftBraceToken().withTrailingNewline,
+            cases: switchCases()
+        )
     }
 
     private func switchCases() -> SwitchCaseListSyntax {
         SwitchCaseListSyntax(
             cases.map { enumCase in
                 .switchCase(
-                    SwitchCaseSyntax(
-                        "case \(switchCase(for: enumCase)): \(statementsBuilder(enumCase))"
-                    )
+                    SwitchCaseSyntax("""
+                    case \(switchCase(for: enumCase)):
+                        \(statementsBuilder(enumCase))\n
+                    """)
                 )
             }
         )
@@ -60,7 +65,7 @@ public struct SwitchExprBuilder: ExprBuilder {
 
         return SwitchCaseItemSyntax(
             pattern: ValueBindingPatternSyntax(
-                bindingSpecifier: .keyword(.let),
+                bindingSpecifier: .keyword(.let).withTrailingSpace,
                 pattern: ExpressionPatternSyntax(
                     expression: FunctionCallExprSyntax(
                         calledExpression: memberAccessExpression,

Sources/PrincipleMacros/Builders/Expressions/SwitchExprBuilder.swift

@@ -6,8 +6,8 @@
 //  Copyright © 2025 Kamil Strzelecki. All rights reserved.
 //
 
-@_exported import SwiftBasicFormat
-@_exported import SwiftDiagnostics
-@_exported import SwiftSyntax
-@_exported import SwiftSyntaxBuilder
-@_exported import SwiftSyntaxMacros
+@_documentation(visibility: private) @_exported import SwiftBasicFormat
+@_documentation(visibility: private) @_exported import SwiftDiagnostics
+@_documentation(visibility: private) @_exported import SwiftSyntax
+@_documentation(visibility: private) @_exported import SwiftSyntaxBuilder
+@_documentation(visibility: private) @_exported import SwiftSyntaxMacros

Sources/PrincipleMacros/Imports.swift

@@ -0,0 +1,51 @@
+//
+//  EnumCaseCallExprBuilderTests.swift
+//  PrincipleMacros
+//
+//  Created by Kamil Strzelecki on 05/04/2025.
+//  Copyright © 2025 Kamil Strzelecki. All rights reserved.
+//
+
+@testable import PrincipleMacros
+import Testing
+
+internal struct EnumCaseCallExprBuilderTests {
+
+    func makeEnumCase(from decl: DeclSyntax) throws -> EnumCase {
+        let enumCaseDecl = try #require(EnumCaseDeclSyntax(decl))
+        let enumElement = try #require(enumCaseDecl.elements.first)
+        return EnumCase(declaration: enumCaseDecl, element: enumElement)
+    }
+
+    @Test
+    func testCallWithoutAssociatedValues() throws {
+        let enumCase = try makeEnumCase(from: "case first")
+        let builder = EnumCaseCallExprBuilder(for: enumCase) { _ in
+            Issue.record()
+            return "" as ExprSyntax
+        }
+        #expect(builder.build().description == ".first")
+    }
+
+    @Test
+    func testCallWithUnnamedAssociatedValue() throws {
+        let enumCase = try makeEnumCase(from: "case second(Int)")
+        let builder = EnumCaseCallExprBuilder(for: enumCase) { _ in
+            "123" as ExprSyntax
+        }
+        #expect(builder.build().description == ".second(123)")
+    }
+
+    @Test
+    func testCallWithMultipleAssociatedValues() throws {
+        let enumCase = try makeEnumCase(from: "case third(arg: String, Int)")
+        let builder = EnumCaseCallExprBuilder(for: enumCase) { associatedValue in
+            if associatedValue.standardizedName.description == "arg" {
+                "argument" as ExprSyntax
+            } else {
+                "123" as ExprSyntax
+            }
+        }
+        #expect(builder.build().description == ".third(arg: argument, 123)")
+    }
+}