Merge branch 'main' into 59-support-orderedmaprange-callbacks-mutating-the-map

Author: fgm

.github/dependabot.yml

@@ -13,4 +13,4 @@ updates:
   - package-ecosystem: github-actions
     directory: /
     schedule:
-      interval: daily
+      interval: "weekly"

.github/workflows/codeql.yml

@@ -12,16 +12,20 @@
 name: "CodeQL Advanced"
 
 on:
+  # For Branch-Protection check. Only the default branch is supported. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
+  #branch_protection_rule:
   push:
     branches: [ "main" ]
   pull_request:
+    # The branches below must be a subset of the branches above
     branches: [ "main" ]
+  # To guarantee Maintained check is occasionally updated. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
   schedule:
     - cron: '45 6 * * 6'
 
-# permissions:
-#   contents: read
-
+# Declare default permissions as read only.
 permissions:
   contents: read
 
@@ -34,6 +38,7 @@ jobs:
     #   - https://gh.io/using-larger-runners (GitHub.com only)
     # Consider using larger runners or machines with greater resources for possible analysis time improvements.
     runs-on: ubuntu-latest
+    # timeout-minutes: 360
     permissions:
       # required for all workflows
       security-events: write
@@ -75,10 +80,17 @@ jobs:
       # or others). This is typically only required for manual builds.
       # - name: Setup runtime (example)
       #   uses: actions/setup-example@v1
+      - name: Set up required Go version
+        uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6.0.0
+        with:
+          go-version: 1.24
+
+      - name: Ensure actual Go version
+        run: go version
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@192325c86100d080feab897ff886c34abd4c83a3 # v3.30.3
+        uses: github/codeql-action/init@3599b3baa15b485a2e49ef411a7a4bb2452e7f93 # v3.30.5
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
@@ -89,13 +101,12 @@ jobs:
           # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
           # queries: security-extended,security-and-quality
 
-      # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+      # Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@192325c86100d080feab897ff886c34abd4c83a3 # v3.30.3
+        uses: github/codeql-action/autobuild@3599b3baa15b485a2e49ef411a7a4bb2452e7f93 # v3.30.5
       #   If the Autobuild fails above, remove it and uncomment the following three lines.
       #   modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance.
-
       # - run: |
       #   echo "Run, Build Application using script"
       #   ./location_of_script_within_repo/buildscript.sh
@@ -116,10 +127,8 @@ jobs:
           echo '  make bootstrap'
           echo '  make release'
           exit 1
-          
-          
-          - name: Perform CodeQL Analysis
+
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@192325c86100d080feab897ff886c34abd4c83a3 # v3.30.3
+        uses: github/codeql-action/analyze@3599b3baa15b485a2e49ef411a7a4bb2452e7f93 # v3.30.5
         with:
           category: "/language:${{matrix.language}}"

.github/workflows/dependency-review.yml

@@ -24,4 +24,4 @@ jobs:
       - name: 'Checkout Repository'
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       - name: 'Dependency Review'
-        uses: actions/dependency-review-action@595b5aeba73380359d98a5e087f648dbb0edce1b # v4.7.3
+        uses: actions/dependency-review-action@56339e523c0409420f6c2c9a2f4292bbb3c07dd3 # v4.8.0

.github/workflows/scorecard.yml

@@ -61,18 +61,21 @@ jobs:
           #     of the value entered here.
           publish_results: true
 
+          # (Optional) Uncomment file_mode if you have a .gitattributes with files marked export-ignore
+          # file_mode: git
+
       # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
       # format to the repository Actions tab.
       - name: "Upload artifact"
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
-          name: SARIF file
+          name: SARIF-file
           path: results.sarif
           retention-days: 5
 
       # Upload the results to GitHub's code scanning dashboard (optional).
       # Commenting out will disable upload of results to your repo's Code Scanning dashboard
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@192325c86100d080feab897ff886c34abd4c83a3 # v3.30.3
+        uses: github/codeql-action/upload-sarif@3599b3baa15b485a2e49ef411a7a4bb2452e7f93 # v3.30.5
         with:
           sarif_file: results.sarif

.github/workflows/workflow.yml

@@ -26,9 +26,9 @@ jobs:
       with:
         go-version: 1.24
 
-    - name: Test
+    - name: Test and cover
       # We don't need the benchmarks to run for long, just enough for coverage.
-      run: mkdir -p coverage; go test -v -race -run=. -bench=. -benchtime=1ms -coverprofile=./coverage/cover.out -covermode=atomic ./...
+      run: mkdir -p coverage; make cover
 
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@5a1091511ad55cbe89839c7260b706298ca349f7 # v5.5.1

.idea/vcs.xml

@@ -0,0 +1,32 @@
+all: lint build
+
+.PHONY: lint test build
+lint:
+	go tool staticcheck ./...
+
+.PHONY: fuzz-smoke
+fuzz-smoke: lint
+	# Smoke tests on fuzzing targets.
+	go test -fuzz='\QFuzzBasicMapAdd\E'   -fuzztime=10s ./set
+	go test -fuzz='\QFuzzBasicMapItems\E' -fuzztime=10s ./set
+	go test -fuzz='\QFuzzBasicMapUnion\E' -fuzztime=10s ./set
+
+.PHONY: bench
+bench:
+	# Run this when modifying the code to obtain data to update BENCHMARKS.md
+	go test -bench=Benchmark ./...
+
+.PHONY: cover
+cover:
+	# This runs the benchmarks just once, as unit tests, for coverage reporting only.
+	# It does not replace running "make bench".
+	go test -v -race -run=. -bench=. -benchtime=1x -coverprofile=coverage/cover.out -covermode=atomic ./...
+
+.PHONY: test
+test:
+	# This includes the fuzz tests in unit test mode
+	go test -race ./...
+
+.PHONY: build
+build: test fuzz-smoke
+	go build ./...

Makefile

@@ -125,28 +125,39 @@ for i := 0; i < 2; i++ {
 }
 ```
 
-### Running tests
-#### Normal tests: unit and benchmarks
+### Development
 
-The complete test coverage requires running not only the unit tests, but also
-the benchmarks, like:
+Since this is a library, it has no install process, but you can build it to ensure correctness, with:
 
 ```
-    go test -race -run=. -bench=. -coverprofile=cover.out -covermode=atomic ./...
+    make lint      # Run staticcheck linting checks
+    make build     # Build the library. Include test and fuzz-smoke targets.
+    make           # Shortcut for make lint && make build
 ```
 
-This will also run the fuzz tests in unit test mode, without triggering the fuzzing logic.
+#### Running normal tests: unit and benchmarks
+
+For the simple version, without generating coverage reports, run:
+```
+    make test       # Unit tests, fast
+    make coverage   # Coverage report in cover.out. A bit longer.
+    make bench      # Benchmarks: run to update BENCHMARKS.md
+    make fuzz-smoke # Fuzz tests as smoke tests: 10 seconds only, for CI builds
+```
+
+This will also run the fuzz tests in unit test mode, 
+without triggering the fuzzing logic.
 
 
-#### Fuzz tests
+#### Running fuzz tests
 
 Fuzz tests are not run by CI, but you can run them on-demand during development with:
 
 ```
-    go test -run='^$' -fuzz='^\QFuzzBasicMapAdd\E$'   -fuzztime=20s ./set
-    go test -run='^$' -fuzz='^\QFuzzBasicMapItems\E$' -fuzztime=20s ./set
-    go test -run='^$' -fuzz='^\QFuzzBasicMapUnion\E$' -fuzztime=20s ./set
+    go test -fuzz='\QFuzzBasicMapAdd\E'   -fuzztime=20s ./set
+    go test -fuzz='\QFuzzBasicMapItems\E' -fuzztime=20s ./set
+    go test -fuzz='\QFuzzBasicMapUnion\E' -fuzztime=20s ./set
 ``` 
 
 - Adjust `-fuzztime` duration as relevant: 20 seconds is just a smoke test.
-- Be sure to escape the `^$` and `\Q\E` characters in the `-fuzz` argument in your shell.
+- Be sure to escape the `\Q\E` characters in the `-fuzz` argument in your shell.

README.md

@@ -5,9 +5,16 @@ go 1.24.7
 require github.com/google/go-cmp v0.7.0
 
 require (
+	github.com/BurntSushi/toml v1.4.1-0.20240526193622-a339e1f7089c // indirect
+	golang.org/x/exp/typeparams v0.0.0-20231108232855-2478ac86f678 // indirect
 	golang.org/x/mod v0.28.0 // indirect
 	golang.org/x/sync v0.17.0 // indirect
 	golang.org/x/tools v0.37.0 // indirect
+	golang.org/x/tools/go/expect v0.1.1-deprecated // indirect
+	honnef.co/go/tools v0.6.1 // indirect
 )
 
-tool golang.org/x/tools/cmd/stringer
+tool (
+	golang.org/x/tools/cmd/stringer
+	honnef.co/go/tools/cmd/staticcheck
+)

go.mod

@@ -1,8 +1,16 @@
+github.com/BurntSushi/toml v1.4.1-0.20240526193622-a339e1f7089c h1:pxW6RcqyfI9/kWtOwnv/G+AzdKuy2ZrqINhenH4HyNs=
+github.com/BurntSushi/toml v1.4.1-0.20240526193622-a339e1f7089c/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+golang.org/x/exp/typeparams v0.0.0-20231108232855-2478ac86f678 h1:1P7xPZEwZMoBoz0Yze5Nx2/4pxj6nw9ZqHWXqP0iRgQ=
+golang.org/x/exp/typeparams v0.0.0-20231108232855-2478ac86f678/go.mod h1:AbB0pIl9nAr9wVwH+Z2ZpaocVmF5I4GyWCDIsVjR0bk=
 golang.org/x/mod v0.28.0 h1:gQBtGhjxykdjY9YhZpSlZIsbnaE2+PgjfLWUQTnoZ1U=
 golang.org/x/mod v0.28.0/go.mod h1:yfB/L0NOf/kmEbXjzCPOx1iK1fRutOydrCMsqRhEBxI=
 golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
 golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/tools v0.37.0 h1:DVSRzp7FwePZW356yEAChSdNcQo6Nsp+fex1SUW09lE=
 golang.org/x/tools v0.37.0/go.mod h1:MBN5QPQtLMHVdvsbtarmTNukZDdgwdwlO5qGacAzF0w=
+golang.org/x/tools/go/expect v0.1.1-deprecated h1:jpBZDwmgPhXsKZC6WhL20P4b/wmnpsEAGHaNy0n/rJM=
+golang.org/x/tools/go/expect v0.1.1-deprecated/go.mod h1:eihoPOH+FgIqa3FpoTwguz/bVUSGBlGQU67vpBeOrBY=
+honnef.co/go/tools v0.6.1 h1:R094WgE8K4JirYjBaOpz/AvTyUu/3wbmAoskKN/pxTI=
+honnef.co/go/tools v0.6.1/go.mod h1:3puzxxljPCe8RGJX7BIy1plGbxEOZni5mR2aXe3/uk4=