V3 Beta 1

.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(dotnet build:*)",
+      "Bash(dotnet pack:*)",
+      "Bash(dotnet test:*)",
+      "Bash(git mv:*)",
+      "Bash(grep -i \"nullable\" /e/Repos/LibSharp/src/LibSharp/*.csproj /e/Repos/LibSharp/test/LibSharp.UnitTests/*.csproj /e/Repos/LibSharp/benchmarks/LibSharp.Benchmarks/*.csproj)",
+      "Bash(grep -n \"^\\\\s*\\\\\\(public\\\\|internal\\\\\\)\\\\s*\\\\\\(abstract\\\\|sealed\\\\|static\\\\\\)\\\\?\\\\s*class\\\\|^\\\\s*\\\\\\(public\\\\|internal\\\\\\)\\\\s*\\\\\\(abstract\\\\|sealed\\\\|static\\\\\\)\\\\?\\\\s*record\" e:/Repos/LibSharp/src/LibSharp/Caching/*.cs)",
+      "Bash(ls e:/Repos/LibSharp/*.md)",
+      "Bash(powershell.exe -Command \"Get-Process -Name testhost -ErrorAction SilentlyContinue | Stop-Process -Force; Write-Host done\")"
+    ]
+  }
+}

.editorconfig

@@ -125,6 +125,7 @@ csharp_style_var_when_type_is_apparent = false:error
 # Expression-bodied members
 csharp_style_expression_bodied_accessors = true:silent
 csharp_style_expression_bodied_constructors = false:error
+csharp_style_prefer_primary_constructors = false:error
 csharp_style_expression_bodied_indexers = true:silent
 csharp_style_expression_bodied_lambdas = true:silent
 csharp_style_expression_bodied_local_functions = false:error
@@ -153,6 +154,7 @@ csharp_prefer_simple_default_expression = true:suggestion
 csharp_style_deconstructed_variable_declaration = true:suggestion
 csharp_style_inlined_variable_declaration = true:suggestion
 csharp_style_pattern_local_over_anonymous_function = true:suggestion
+csharp_style_prefer_collection_expression = false:error
 csharp_style_prefer_index_operator = true:suggestion
 csharp_style_prefer_range_operator = true:suggestion
 csharp_style_throw_expression = true:suggestion
@@ -166,7 +168,7 @@ csharp_style_implicit_object_creation_when_type_is_apparent = false
 csharp_using_directive_placement = outside_namespace:error
 
 # Other
-csharp_style_namespace_declarations = block_scoped:silent
+csharp_style_namespace_declarations = file_scoped:error
 csharp_style_prefer_method_group_conversion = true:silent
 csharp_style_prefer_top_level_statements = true:silent
 csharp_style_prefer_null_check_over_type_check = true:suggestion
@@ -279,76 +281,76 @@ dotnet_naming_rule.const_field_should_be_pascal_case.style = pascal_case
 
 dotnet_naming_symbols.class.applicable_kinds = class
 dotnet_naming_symbols.class.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
-dotnet_naming_symbols.class.required_modifiers = 
+dotnet_naming_symbols.class.required_modifiers =
 
 dotnet_naming_symbols.interface.applicable_kinds = interface
 dotnet_naming_symbols.interface.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
-dotnet_naming_symbols.interface.required_modifiers = 
+dotnet_naming_symbols.interface.required_modifiers =
 
 dotnet_naming_symbols.struct.applicable_kinds = struct
 dotnet_naming_symbols.struct.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
-dotnet_naming_symbols.struct.required_modifiers = 
+dotnet_naming_symbols.struct.required_modifiers =
 
 dotnet_naming_symbols.enum.applicable_kinds = enum
 dotnet_naming_symbols.enum.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
-dotnet_naming_symbols.enum.required_modifiers = 
+dotnet_naming_symbols.enum.required_modifiers =
 
 dotnet_naming_symbols.method.applicable_kinds = method
 dotnet_naming_symbols.method.applicable_accessibilities = public
-dotnet_naming_symbols.method.required_modifiers = 
+dotnet_naming_symbols.method.required_modifiers =
 
 dotnet_naming_symbols.property.applicable_kinds = property
 dotnet_naming_symbols.property.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
-dotnet_naming_symbols.property.required_modifiers = 
+dotnet_naming_symbols.property.required_modifiers =
 
 dotnet_naming_symbols.public_or_protected_field.applicable_kinds = field
 dotnet_naming_symbols.public_or_protected_field.applicable_accessibilities = public, protected
-dotnet_naming_symbols.public_or_protected_field.required_modifiers = 
+dotnet_naming_symbols.public_or_protected_field.required_modifiers =
 
 dotnet_naming_symbols.static_field.applicable_kinds = field
 dotnet_naming_symbols.static_field.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
 dotnet_naming_symbols.static_field.required_modifiers = static
 
 dotnet_naming_symbols.private_or_internal_field.applicable_kinds = field
 dotnet_naming_symbols.private_or_internal_field.applicable_accessibilities = internal, private, private_protected
-dotnet_naming_symbols.private_or_internal_field.required_modifiers = 
+dotnet_naming_symbols.private_or_internal_field.required_modifiers =
 
 dotnet_naming_symbols.private_or_internal_static_field.applicable_kinds = field
 dotnet_naming_symbols.private_or_internal_static_field.applicable_accessibilities = internal, private, private_protected
 dotnet_naming_symbols.private_or_internal_static_field.required_modifiers = static
 
 dotnet_naming_symbols.types.applicable_kinds = class, struct, interface, enum
 dotnet_naming_symbols.types.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
-dotnet_naming_symbols.types.required_modifiers = 
+dotnet_naming_symbols.types.required_modifiers =
 
 dotnet_naming_symbols.non_field_members.applicable_kinds = property, event, method
 dotnet_naming_symbols.non_field_members.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
-dotnet_naming_symbols.non_field_members.required_modifiers = 
+dotnet_naming_symbols.non_field_members.required_modifiers =
 
 dotnet_naming_symbols.const_field.applicable_kinds = field
 dotnet_naming_symbols.const_field.applicable_accessibilities = *
 dotnet_naming_symbols.const_field.required_modifiers = const
 
 # Naming styles
 
-dotnet_naming_style.pascal_case.required_prefix = 
-dotnet_naming_style.pascal_case.required_suffix = 
-dotnet_naming_style.pascal_case.word_separator = 
+dotnet_naming_style.pascal_case.required_prefix =
+dotnet_naming_style.pascal_case.required_suffix =
+dotnet_naming_style.pascal_case.word_separator =
 dotnet_naming_style.pascal_case.capitalization = pascal_case
 
 dotnet_naming_style.begins_with_i.required_prefix = I
-dotnet_naming_style.begins_with_i.required_suffix = 
-dotnet_naming_style.begins_with_i.word_separator = 
+dotnet_naming_style.begins_with_i.required_suffix =
+dotnet_naming_style.begins_with_i.word_separator =
 dotnet_naming_style.begins_with_i.capitalization = pascal_case
 
 dotnet_naming_style.class_member.required_prefix = m_
-dotnet_naming_style.class_member.required_suffix = 
-dotnet_naming_style.class_member.word_separator = 
+dotnet_naming_style.class_member.required_suffix =
+dotnet_naming_style.class_member.word_separator =
 dotnet_naming_style.class_member.capitalization = camel_case
 
 dotnet_naming_style.static_class_member.required_prefix = s_
-dotnet_naming_style.static_class_member.required_suffix = 
-dotnet_naming_style.static_class_member.word_separator = 
+dotnet_naming_style.static_class_member.required_suffix =
+dotnet_naming_style.static_class_member.word_separator =
 dotnet_naming_style.static_class_member.capitalization = camel_case
 
 #### .NET diagnostics ####

.github/workflows/benchmarks.yml

@@ -0,0 +1,139 @@
+name: Benchmarks
+
+on:
+  workflow_dispatch:
+    inputs:
+      filter:
+        description: BenchmarkDotNet filter expression
+        required: false
+        default: '*'
+        type: string
+      compare_previous_commit:
+        description: Run benchmarks on previous commit and compare
+        required: false
+        default: false
+        type: boolean
+      regression_threshold:
+        description: Fail if mean regression exceeds this percentage (0 disables)
+        required: false
+        default: '0'
+        type: string
+  push:
+    branches:
+      - main
+    paths:
+      - src/**
+      - benchmarks/**
+      - LibSharp.sln
+      - .github/workflows/benchmarks.yml
+  schedule:
+    - cron: '0 4 * * 1'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: benchmarks-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  benchmarks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 10.0.x
+
+      - name: Resolve run labels and filter
+        id: vars
+        shell: bash
+        run: |
+          echo "before_label=before-${{ github.run_id }}-${{ github.run_attempt }}" >> "$GITHUB_OUTPUT"
+          echo "after_label=after-${{ github.run_id }}-${{ github.run_attempt }}" >> "$GITHUB_OUTPUT"
+
+          FILTER='*'
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ -n "${{ inputs.filter }}" ]; then
+            FILTER='${{ inputs.filter }}'
+          fi
+
+          echo "filter=$FILTER" >> "$GITHUB_OUTPUT"
+
+      - name: Restore dependencies
+        run: dotnet restore LibSharp.sln
+
+      - name: Run benchmarks (current commit)
+        shell: pwsh
+        run: |
+          ./benchmarks/run-benchmarks.ps1 -Label "${{ steps.vars.outputs.after_label }}" -Filter "${{ steps.vars.outputs.filter }}"
+
+      - name: Upload benchmark artifacts (current commit)
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results-${{ steps.vars.outputs.after_label }}
+          path: benchmarks/results/${{ steps.vars.outputs.after_label }}
+          if-no-files-found: error
+
+      - name: Detect previous commit
+        id: prev
+        if: github.event_name == 'workflow_dispatch' && inputs.compare_previous_commit
+        shell: bash
+        run: |
+          if git rev-parse --verify HEAD^ >/dev/null 2>&1; then
+            echo "has_previous=true" >> "$GITHUB_OUTPUT"
+            echo "previous_sha=$(git rev-parse HEAD^)" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_previous=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Run benchmarks (previous commit)
+        id: previous
+        if: github.event_name == 'workflow_dispatch' && inputs.compare_previous_commit && steps.prev.outputs.has_previous == 'true'
+        shell: bash
+        run: |
+          CURRENT_SHA="${{ github.sha }}"
+          PREVIOUS_SHA="${{ steps.prev.outputs.previous_sha }}"
+
+          echo "comparison_ready=false" >> "$GITHUB_OUTPUT"
+
+          git checkout --detach "$PREVIOUS_SHA"
+
+          if [ ! -f "benchmarks/run-benchmarks.ps1" ]; then
+            echo "Skipping previous commit benchmark run: benchmarks script not found."
+            git checkout --detach "$CURRENT_SHA"
+            exit 0
+          fi
+
+          pwsh ./benchmarks/run-benchmarks.ps1 -Label "${{ steps.vars.outputs.before_label }}" -Filter "${{ steps.vars.outputs.filter }}"
+
+          git checkout --detach "$CURRENT_SHA"
+          echo "comparison_ready=true" >> "$GITHUB_OUTPUT"
+
+      - name: Compare benchmark runs
+        if: github.event_name == 'workflow_dispatch' && inputs.compare_previous_commit && steps.prev.outputs.has_previous == 'true' && steps.previous.outputs.comparison_ready == 'true'
+        shell: pwsh
+        run: |
+          [double]$threshold = 0
+          [double]::TryParse('${{ inputs.regression_threshold }}', [ref]$threshold) | Out-Null
+
+          ./benchmarks/compare-benchmarks.ps1 `
+            -Before "${{ steps.vars.outputs.before_label }}" `
+            -After "${{ steps.vars.outputs.after_label }}" `
+            -RegressionThreshold $threshold
+
+      - name: Upload benchmark artifacts (comparison)
+        if: github.event_name == 'workflow_dispatch' && inputs.compare_previous_commit && steps.prev.outputs.has_previous == 'true' && steps.previous.outputs.comparison_ready == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-comparison-${{ github.run_id }}-${{ github.run_attempt }}
+          path: |
+            benchmarks/results/${{ steps.vars.outputs.before_label }}
+            benchmarks/results/comparison-${{ steps.vars.outputs.after_label }}-vs-${{ steps.vars.outputs.before_label }}.csv
+          if-no-files-found: warn

.github/workflows/ci-tests.yml

@@ -0,0 +1,38 @@
+name: Unit Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: unit-tests-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 10.0.x
+
+      - name: Restore dependencies
+        run: dotnet restore LibSharp.sln
+
+      - name: Build
+        run: dotnet build LibSharp.sln -c Release --no-restore
+
+      - name: Test
+        run: dotnet test test/LibSharp.UnitTests/LibSharp.UnitTests.csproj -c Release --no-build --verbosity normal

.gitignore

@@ -5,3 +5,5 @@ obj/
 TestResults/
 coveragereport/
 *.user
+benchmarks/results/
+BenchmarkDotNet.Artifacts/