Add LSB parsing support to bitmask (#29)

## Goal

This PR adds LSB parsing support to bitmask. 

The bitmask parsing is defaulted to MSB (BE). To opt in LSB (LE)
parsing, one needs to specify in the `@ParseStrucut`, `@ParseEnum`, and
`@ParseBitmask` macro with `bitEndian: .little`.

## Design

This PR replaces the old RawBitsInteger-based approach with a new
RawBitsSpan type and uses it to enable endianness-aware bit-level
parsing.

### RawBitsSpan

RawBitsSpan is a ~Escapable, ~Copyable span type that provides a
zero-copy view into a contiguous byte buffer with bit-level granularity.
It tracks a _bitOffset and _bitCount into an underlying Span<UInt8>.

Key operations:

- `load(as:bitCount:)` — extracts bits as a right-aligned fixed-width
integer
- `extracting(first:)` / `extracting(last:)` — non-mutating sub-span
extraction
- `slicing(first:)` / `slicing(last:)` — mutating extraction that
consumes bits from the span

This replaces the previous design where all bits were pre-extracted into
a FixedWidthInteger (RawBitsInteger associated type). The span-based
approach removes the 64/128-bit size limit, avoids copying bits into an
integer container, and decouples conforming types from a specific
integer width.

### Endianness flow

The bitEndian parameter flows through the system as follows:

1. Declaration — user specifies bitEndian: .little on the macro
attribute
2. Macro expansion — MacroConfigurationVisitor extracts the value and
stores it in AccessorInfo
3. Code generation — the macro generates RawBitsSpan initialization and
field slicing calls:
- Big endian (default): span starts at bit offset 0, fields are sliced
with `__slicing(unchecked: (), first:)`, consuming from MSB toward LSB
- Little endian: span starts at bit offset totalBytes * 8 - totalBits,
fields are sliced with `__slicing(unchecked: (), last:)`, consuming from
LSB toward MSB
4. Runtime — `__createFromBits` adjusts the span when
`fieldRequestedBitCount > typeBitCount`, extracting from first (big) or
last (little) to select the significant bits

### ExpressibleByRawBits protocol change

The protocol no longer has an associated `RawBitsInteger` type. The
initializer now takes borrowing RawBitsSpan:

```swift
public protocol ExpressibleByRawBits {
    init(bits: borrowing RawBitsSpan) throws
}
```

Conformances for `Bool`, `UInt8`, `Int8`, and other integer types
extract only the bits they need via RawBitsSpan.load().

### Other changes

- CI updated to use Swiftly
- Benchmarks disabled by default
- Removed `__maskParsing` and `ExtractBitsAsIntegerTests` /
`MaskParsingTests` (superseded by `RawBitsSpan` and new tests)
- Refactored macro utility naming (`MacroConfigurationVisitor`,
`extractMacroConfiguration`)
- Added comprehensive test coverage for both endianness modes across
bitmask, enum, and struct parsing

Author: FlickerSoul

.github/workflows/benchmark.yml

@@ -16,18 +16,31 @@ jobs:
     name: Run Benchmarks
     if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
     runs-on: macOS-26
-    env:
-      DEVELOPER_DIR: "/Applications/Xcode_26.1.app/Contents/Developer"
     steps:
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
+      - name: Install Swiftly And Swift
+        run: |
+          curl -L https://download.swift.org/swiftly/darwin/swiftly.pkg > swiftly.pkg
+          installer -pkg swiftly.pkg -target CurrentUserHomeDirectory
+
+          ~/.swiftly/bin/swiftly init
+
+          . "$HOME/.swiftly/env.sh"
+          hash -r
+
+          swiftly install --use --assume-yes
+          swiftly link --assume-yes
+
+          echo "$HOME/.swiftly/bin" >> $GITHUB_PATH
       - name: Swift Version
-        run: xcrun swift --version
+        run: which swift && swift --version
       - name: Install jemalloc
         run: |
           echo "/opt/homebrew/bin:/usr/local/bin" >> $GITHUB_PATH
           brew install jemalloc
       - name: Run Parsing Benchmarks
         run: |
-          xcrun swift package benchmark --no-progress --format markdown >> $GITHUB_STEP_SUMMARY
+          export ENABLE_BENCHMARK=1
+          swift package benchmark --no-progress --format markdown >> $GITHUB_STEP_SUMMARY

.github/workflows/ci.yml

@@ -23,46 +23,55 @@ jobs:
   lint:
     name: Lint & Format Check
     runs-on: macOS-26
-    env:
-      DEVELOPER_DIR: "/Applications/Xcode_26.1.app/Contents/Developer"
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-      - name: Swift Version
-        run: xcrun swift --version
       - name: Install SwiftLint
         run: brew install swiftlint --quiet
       - name: Install swift-format
         run: brew install swiftformat --quiet
       - name: SwiftLint
-        run: swiftlint --strict --config .swiftlint.yml .
+        run: swiftlint --strict --config .swiftlint.yml . --reporter github-actions-logging
       - name: Swift Format Check
-        run: swiftformat --lint-only --config .swiftformat.conf . --strict
+        run: swiftformat --lint-only --config .swiftformat.conf . --strict --reporter github-actions-log --verbose
   test:
     name: ${{ matrix.name }}
     runs-on: ${{ matrix.runsOn }}
     needs: lint
-    env:
-      DEVELOPER_DIR: "/Applications/${{ matrix.xcode }}.app/Contents/Developer"
     strategy:
       matrix:
         include:
-          - xcode: "Xcode_26.0"
-            runsOn: macOS-26
+          - runsOn: macOS-26
             name: "macOS 26, SPM 6.2.0 Test"
     steps:
       - uses: actions/checkout@v4
+      - name: Install Swiftly And Swift
+        run: |
+          curl -L https://download.swift.org/swiftly/darwin/swiftly.pkg > swiftly.pkg
+          installer -pkg swiftly.pkg -target CurrentUserHomeDirectory
+
+          ~/.swiftly/bin/swiftly init
+
+          . "$HOME/.swiftly/env.sh"
+          hash -r
+
+          swiftly install --use --assume-yes
+          swiftly link --assume-yes
+
+          echo "$HOME/.swiftly/bin" >> $GITHUB_PATH
       - name: Swift Version
-        run: xcrun swift --version
-      - name: Install xcbeautify
+        run: which swift && swift --version
+      - name: Brew install tools
         run: brew install xcbeautify --quiet
       - name: Run Tests
         run: |
-          set -o pipefail && \
-          xcodebuild test \
-          -scheme BinaryParseKit \
-          -destination 'platform=macOS' \
-          -skipMacroValidation | xcbeautify --renderer github-actions
+          defaults write com.apple.dt.Xcode IDEPackageEnablePrebuilts YES
+
+          # set -o pipefail && \
+          # xcodebuild test \
+          # -scheme BinaryParseKit \
+          # -destination 'platform=macOS' \
+          # -skipMacroValidation | xcbeautify --renderer github-actions
 
           # https://github.com/swiftlang/swift-package-manager/issues/9163
-          # set -o pipefail && xcrun swift test -c debug --enable-code-coverage --xunit-output $TEST_RESULTS_DIR/xunit.xml 2>&1 | xcbeautify --renderer github-actions
+          set -o pipefail && swift test | xcbeautify --renderer github-actions

.github/workflows/deploy-docc.yml

@@ -14,17 +14,29 @@ jobs:
   build:
     name: Build DocC Documentation
     runs-on: macOS-26
-    env:
-      DEVELOPER_DIR: "/Applications/Xcode_26.1.app/Contents/Developer"
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+      - name: Install Swiftly And Swift
+        run: |
+          curl -L https://download.swift.org/swiftly/darwin/swiftly.pkg > swiftly.pkg
+          installer -pkg swiftly.pkg -target CurrentUserHomeDirectory
+
+          ~/.swiftly/bin/swiftly init
+
+          . "$HOME/.swiftly/env.sh"
+          hash -r
+
+          swiftly install --use --assume-yes
+          swiftly link --assume-yes
+
+          echo "$HOME/.swiftly/bin" >> $GITHUB_PATH
       - name: Swift Version
-        run: xcrun swift --version
+        run: which swift && swift --version
       - name: Build DocC
         run: |
-          xcrun swift build
-          xcrun swift package --allow-writing-to-directory ./docs \
+          swift build
+          swift package --allow-writing-to-directory ./docs \
             generate-documentation \
             --enable-experimental-combined-documentation \
             --target BinaryParseKit \

.swift-version

@@ -1 +1 @@
-6.2
+6.2.3

.swiftlint.yml

@@ -20,7 +20,7 @@ function_body_length:
   warning: 300
   error: 500
 file_length:
-  warning: 800
+  warning: 1000
   error: 1200
   ignore_comment_only_lines: true
 large_tuple:
@@ -33,6 +33,7 @@ identifier_name:
     - j
     - x
     - y
+    - "b[0-9]"
   allowed_symbols: ["_", " "]
 cyclomatic_complexity:
   warning: 20

Benchmarks/BenchmarkTypes/BenchmarkBitmaskComplex.swift

@@ -11,8 +11,6 @@ import Foundation
 
 @ParseBitmask
 public struct BenchmarkBitmaskComplex: Equatable, Sendable, BaselineParsable {
-    public typealias RawBitsInteger = UInt32
-
     @mask(bitCount: 1)
     public var flag1: UInt8
 

Benchmarks/BenchmarkTypes/BenchmarkBitmaskSimple.swift

@@ -11,8 +11,6 @@ import Foundation
 
 @ParseBitmask
 public struct BenchmarkBitmaskSimple: Equatable, Sendable, BaselineParsable {
-    public typealias RawBitsInteger = UInt8
-
     @mask(bitCount: 1)
     public var flag: UInt8
 

Benchmarks/BenchmarkTypes/NonByteAlignedBitmask.swift

@@ -11,8 +11,6 @@ import Foundation
 
 @ParseBitmask
 public struct NonByteAlignedBitmask: Equatable, Sendable, BaselineParsable {
-    public typealias RawBitsInteger = UInt16
-
     @mask(bitCount: 3)
     public var first: UInt8
 

Benchmarks/BenchmarkTypes/UInt16+.swift

@@ -8,10 +8,8 @@ import BinaryParseKit
 import Foundation
 
 extension UInt16: ExpressibleByRawBits {
-    public typealias RawBitsInteger = UInt16
-
-    public init(bits: RawBitsInteger) throws {
-        self = bits
+    public init(bits: borrowing RawBitsSpan) throws {
+        self = try bits.load(as: Self.self)
     }
 }
 

Benchmarks/BenchmarkTypes/Utils.swift

@@ -0,0 +1,10 @@
+import Benchmark
+
+public extension Benchmark {
+    @inlinable
+    func context(_ body: () -> Void) {
+        startMeasurement()
+        body()
+        stopMeasurement()
+    }
+}