chore: expand tooling, docs, and test coverage

.devcontainer/devcontainer-lock.json

@@ -0,0 +1,14 @@
+{
+  "features": {
+    "ghcr.io/devcontainers-extra/features/mise:1": {
+      "version": "1.0.0",
+      "resolved": "ghcr.io/devcontainers-extra/features/mise@sha256:5c389ab1e3c8e44e5e0ff119f6868d54dbb781bc860bd8587dc66209cb8c4a8c",
+      "integrity": "sha256:5c389ab1e3c8e44e5e0ff119f6868d54dbb781bc860bd8587dc66209cb8c4a8c"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {
+      "version": "1.1.0",
+      "resolved": "ghcr.io/devcontainers/features/github-cli@sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671",
+      "integrity": "sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671"
+    }
+  }
+}

.devcontainer/devcontainer.json

@@ -1,18 +1,20 @@
- // For format details, see https://aka.ms/devcontainer.json.
+// For format details, see https://aka.ms/devcontainer.json.
 {
     "name": "Ubuntu",
     // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
     "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
     // Features to add to the dev container. More info: https://containers.dev/features.
     "features": {
         "ghcr.io/devcontainers-extra/features/mise:1": {},
-        "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+        "ghcr.io/devcontainers/features/github-cli:1": {}
     },
     "postCreateCommand": "bash .devcontainer/post_create.sh",
     "customizations": {
         "vscode": {
             "extensions": [
-                "golang.go"
+                "golang.go",
+                "hverlin.mise-vscode",
+                "tamasfe.even-better-toml"
             ]
         }
     }

.devcontainer/post_create.sh

@@ -1,9 +1,9 @@
 #!/bin/bash
 
-# note that bash will read from ~/.profile or ~/.bash_profile if the latter exists
-# ergo, you may want to check to see which is defined on your system and only append to the existing file
-echo 'eval "$(mise activate bash --shims)"' >>~/.bash_profile # this sets up non-interactive sessions
-echo 'eval "$(mise activate bash)"' >>~/.bashrc               # this sets up interactive sessions
+set -euo pipefail
+
+echo 'eval "$(mise activate bash --shims)"' >>~/.bash_profile
+echo 'eval "$(mise activate bash)"' >>~/.bashrc
 
 mise trust .
 
@@ -13,3 +13,7 @@ mise exec -- go mod download
 
 mise exec -- go install -v golang.org/x/tools/gopls@latest
 mise exec -- go install -v github.com/go-delve/delve/cmd/dlv@latest
+
+if [[ -f ".devcontainer/post_create.local.sh" ]]; then
+    source ".devcontainer/post_create.local.sh"
+fi

.github/workflows/codeql.yml

@@ -3,49 +3,99 @@
 #
 # You may wish to alter this file to override the set of languages analyzed,
 # or to provide custom queries or build logic.
-name: "CodeQL"
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
 
 on:
   push:
-    branches:
-      - main
+    branches: [ "main" ]
   pull_request:
-    # The branches below must be a subset of the branches above
-    branches:
-      - main
+    branches: [ "main" ]
   schedule:
     - cron: "0 17 * * 5"
 
 jobs:
   analyze:
-    name: Analyze
-    runs-on: ubuntu-latest
-
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - 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: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
     permissions:
       # required for all workflows
       security-events: write
 
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
     strategy:
       fail-fast: false
       matrix:
-        # Override automatic language detection by changing the below list
-        # Supported options are ['csharp', 'cpp', 'go', 'java', 'javascript', 'python']
-        # TODO: Enable for javascript later
-        language: ["go"]
-
+        include:
+        - language: actions
+          build-mode: none
+        - language: go
+          build-mode: autobuild
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v5
-
-      # Initializes the CodeQL tools for scanning.
-      - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4
-        with:
-          languages: ${{ matrix.language }}
-          # If you wish to specify custom queries, you can do so here or in a config file.
-          # By default, queries listed here will override any specified in a config file.
-          # Prefix the list here with "+" to use these queries and those in the config file.
-          # queries: ./path/to/local/query, your-org/your-repo/queries@main
-
-      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v4
+    - name: Checkout repository
+      uses: actions/checkout@v6
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # 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
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - name: Run manual build steps
+      if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+      with:
+        category: "/language:${{matrix.language}}"

.github/workflows/pr-check.yml

@@ -5,18 +5,42 @@ on:
     branches:
       - main
 
+permissions:
+  contents: read
+
+concurrency:
+  group: pr-check-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   check:
     name: Check
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - name: Checkout
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Install mise
-        uses: jdx/mise-action@v4
+        uses: jdx/mise-action@e6a8b3978addb5a52f2b4cd9d91eafa7f0ab959d # v4.2.0
+
+      - name: Cache Go modules and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/go/pkg/mod
+            ~/.cache/go-build
+          key: go-${{ runner.os }}-${{ hashFiles('**/go.sum') }}
+          restore-keys: go-${{ runner.os }}-
+
+      - name: Cache golangci-lint
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/golangci-lint
+          key: golangci-lint-${{ runner.os }}-${{ hashFiles('mise.toml', '.golangci.yaml') }}
+          restore-keys: golangci-lint-${{ runner.os }}-
 
       - name: Download Go dependencies
         run: go mod download

.gitignore

@@ -4,3 +4,8 @@
 # go work
 go.work
 go.work.sum
+
+# Local configuration files
+*.local.*
+*.local/
+*.local

.golangci.yaml

@@ -10,10 +10,6 @@ issues:
 
 severity:
   default: error
-  # rules:
-  #   - linters:
-  #       - dupl
-  #     severity: error
 
 formatters:
   enable:
@@ -22,16 +18,16 @@ formatters:
     - gofumpt
     - goimports
     - golines
-    - swaggo
+
   settings:
     gofmt:
       rewrite-rules:
         - pattern: "interface{}"
           replacement: "any"
     gofumpt:
       extra-rules: true
-  exclusions:
-    paths: []
+    golines:
+      max-len: 120
 
 linters:
   default: none
@@ -45,33 +41,66 @@ linters:
 
     # Additional
     - bodyclose
+    - canonicalheader
+    - copyloopvar
     - depguard
+    - dupword
+    - durationcheck
+    - errchkjson
     - errname
     - errorlint
+    - exptostd
+    - fatcontext
+    - gocheckcompilerdirectives
     - gocognit
     - goconst
-    - goheader
-    - gomodguard
+    - gocritic
+    - gomodguard_v2
     - goprintffuncname
     - gosec
+    - intrange
+    - loggercheck
+    - mirror
+    - misspell
+    - modernize
+    - musttag
     - nakedret
+    - nestif
     - nilerr
+    - nilnesserr
     - nilnil
     - noctx
     - nolintlint
+    - nosprintfhostport
+    - perfsprint
     - prealloc
     - promlinter
+    - recvcheck
     - revive
+    - rowserrcheck
+    - sloglint
+    - spancheck
+    - sqlclosecheck
     - testifylint
     - testpackage
     - thelper
+    - unconvert
+    - unparam
     - usestdlibvars
+    - usetesting
     - wastedassign
+    - whitespace
     - wsl_v5
 
-  disable: []
-
   settings:
+    govet:
+      enable:
+        - nilness
+
+    modernize:
+      disable:
+        - omitzero
+
     depguard:
       rules:
         main:
@@ -84,16 +113,3 @@ linters:
               desc: Use github.com/go-resty/resty/v2 instead
             - pkg: github.com/aws/smithy-go/ptr$
               desc: Use github.com/aws/aws-sdk-go-v2/aws instead
-    govet:
-      enable:
-        - nilness
-
-  # exclusions:
-  #   paths:
-  #     - (.+)_test\.go
-  #   rules:
-  #     - path: (.+)_test\.go
-  #       linters:
-  #         - dupl
-  #         - mnd
-  #         - lll

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+    "recommendations": [
+        "ms-vscode-remote.remote-containers",
+        "golang.go",
+        "hverlin.mise-vscode",
+        "tamasfe.even-better-toml"
+    ]
+}