.golangci.yml

# golangci-lint configuration file
# Documentation: https://golangci-lint.run/usage/configuration/
# Configuration version 2 is required for the latest golangci-lint features
version: "2"

# Run configuration
# These settings control how golangci-lint executes
run:
  # modules-download-mode controls how Go modules are handled during linting
  # Options: readonly (don't download, use cache), vendor (use vendor/ directory), mod (download if needed)
  # Using readonly ensures reproducible builds and prevents network access during linting
  modules-download-mode: readonly
  
  # tests controls whether test files (*_test.go) are linted
  # Set to false to skip linting test files
  tests: false
  
  # allow-parallel-runners enables concurrent execution of multiple golangci-lint instances
  # Useful for CI environments where multiple branches might be linted simultaneously
  allow-parallel-runners: true

# Linters configuration
# Specifies which linters to enable or disable
linters:
  # default: all enables all available linters by default
  # Individual linters are then disabled below based on project needs
  default: all
  
  # disable contains linters that are explicitly turned off
  # Each disabled linter should have a comment explaining why
  disable:
    - cyclop        # Cyclomatic complexity checks - too strict for this project's complexity needs
    - depguard      # Dependency guard - not using package import restrictions
    - dupl          # Duplicate code detection - generates too many false positives for similar API patterns
    - err113        # Error wrapping checks - too strict, project uses custom error handling
    - exhaustive    # Exhaustive enum/switch checks - not all switches need to be exhaustive
    - exhaustruct   # Exhaustive struct initialization - too verbose for common structs
    - forcetypeassert # Forces type assertion checks - project has controlled type assertions
    - funlen        # Function length limits - some complex functions legitimately need more lines
    - gochecknoglobals # Global variable checks - some globals are necessary for package state
    - gocognit      # Cognitive complexity checks - overlaps with cyclop, too strict
    - goconst       # Constant extraction - too aggressive for unique string/number literals
    - ireturn       # Interface return checks - project intentionally returns interfaces in some cases
    - lll           # Line length limits - handled by revive's line-length-limit rule instead
    - maintidx      # Maintainability index - too strict for complex but well-structured code
    - mnd           # Magic number detection - too aggressive, some numbers are self-explanatory
    - musttag       # Struct tag checks - not using special struct tag requirements
    - perfsprint    # Sprint performance checks - negligible performance impact in this codebase
    - tagliatelle   # Struct tag format checks - using default tag formats
    - varnamelen    # Variable name length checks - too strict, short names are acceptable in limited scopes
    - wrapcheck     # Error wrapping checks - project has its own error handling conventions
    - wsl           # Whitespace linter - too opinionated about blank lines
    - wsl_v5        # Whitespace linter v5 - too opinionated about blank lines
    - noinlineerr   # No inline error checks - project uses inline error handling pattern

  # Linter-specific settings
  # Each linter can have custom configuration to fine-tune its behavior
  settings:
    # goheader checks that all source files have the correct copyright header
    # Documentation: https://github.com/denis-tingaikin/go-header
    goheader:
      values:
        # regexp defines template variables that can be matched with regex patterns
        regexp:
          # YEARS matches various copyright year formats (e.g., "2024", "2023 - 2024", "2023, 2024")
          YEARS: (20\d\d - 20\d\d|20\d\d, 20\d\d|20\d\d)
      # template defines the expected file header using Go template syntax
      # {{ YEARS }} is replaced with the regex pattern defined above
      template: |-
        Copyright © {{ YEARS }} Attestant Limited.
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at

            http://www.apache.org/licenses/LICENSE-2.0

        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
    
    # gosec performs security checks for common Go security issues
    # Documentation: https://github.com/securego/gosec
    gosec:
      excludes:
        # G115: Integer overflow checks - excluded as it produces false positives for safe integer operations
        - G115
    
    # lll checks for lines that are too long
    # Note: This linter is disabled, but settings are kept for reference
    lll:
      # line-length sets the maximum allowed line length in characters
      line-length: 132
    
    # nlreturn checks for new lines before return statements
    # Documentation: https://github.com/ssgreg/nlreturn
    nlreturn:
      # block-size specifies the minimum number of lines in a block before requiring a newline before return
      block-size: 3
    
    # revive is a flexible, configurable linter with many rules
    # Documentation: https://github.com/mgechev/revive
    revive:
      # confidence sets the minimum confidence threshold (0.0 to 1.0) for reporting issues
      confidence: 0.8
      # severity sets the default severity level for all rules
      # Options: error, warning
      severity: error
      # enable-all-rules turns on all available revive rules by default
      # Individual rules are then configured or disabled below
      enable-all-rules: true
      rules:
        # add-constant suggests extracting repeated literals into constants
        # Disabled: too aggressive, some literals are self-documenting
        - name: add-constant
          disabled: true
        # cyclomatic checks cyclomatic complexity
        # Disabled: already handled by other complexity checks
        - name: cyclomatic
          disabled: true
        # cognitive-complexity checks cognitive complexity (how hard code is to understand)
        # Disabled: overlaps with cyclomatic and can be too strict
        - name: cognitive-complexity
          disabled: true
        # confusing-results warns about confusing return values (e.g., returning both error and non-nil value)
        # Enabled with default settings
        - name: confusing-results
        # function-length checks if functions are too long
        # Disabled: some complex functions legitimately need more lines
        - name: function-length
          disabled: true
        # line-length-limit checks if lines are too long
        # Set to 132 characters to match project conventions
        - name: line-length-limit
          arguments:
            - 132
        # max-public-structs limits the number of public structs in a package
        # Disabled: API packages naturally have many public types
        - name: max-public-structs
          disabled: true
        # package-comments requires package documentation comments
        # Disabled: not enforcing package-level comments
        - name: package-comments
          disabled: true
        # struct-tag validates struct tags format and correctness
        # Configured to allow json tags with "allowempty" option
        - name: struct-tag
          arguments:
            - json,allowempty
        # unhandled-error warns about ignored error return values
        # Configured to allow ignoring fmt.Fprint and fmt.Fprintf errors (typically to stdout/stderr)
        - name: unhandled-error
          arguments:
            - fmt.Fprint
            - fmt.Fprintf
        # unnecessary-stmt detects unnecessary statements
        # Disabled: can produce false positives for intentional patterns
        - name: unnecessary-stmt
          disabled: true
        # package-directory-mismatch checks if package name matches directory name
        # Disabled: "client" package name is intentional API design
        - name: package-directory-mismatch
          disabled: true
        # unsecure-url-scheme warns about using insecure protocols
        # Disabled: ws:// usage is intentional fallback for local development
        - name: unsecure-url-scheme
          disabled: true
        # var-naming checks for meaningful package names
        # Disabled: "types" and "util" are standard, idiomatic Go package names
        - name: var-naming
          disabled: true
    
    # staticcheck is a comprehensive static analysis tool for Go
    # Documentation: https://staticcheck.io/docs/
    staticcheck:
      checks:
        # all enables all staticcheck checks by default
        - all
        # -ST1000 disables "Incorrect or missing package comment"
        # Excluded: not enforcing package-level documentation comments
        - -ST1000
    
    # tagliatelle checks struct tag naming conventions
    # Note: This linter is disabled, but settings are kept for reference
    # Documentation: https://github.com/ldez/tagliatelle
    tagliatelle:
      case:
        # rules defines the naming convention for different tag types
        rules:
          # json tags should use snake_case
          json: snake
          # yaml tags should use snake_case
          yaml: snake

# Exclusions configuration
# Controls which files and issues are excluded from linting
  exclusions:
    # generated controls how generated files are handled
    # Options: strict (enforce all rules), lax (relax some rules), disable (skip entirely)
    # Using lax to allow some flexibility in generated code while still catching obvious issues
    generated: lax
    
    # presets are predefined sets of exclusions for common false positives
    presets:
      # common-false-positives excludes widely recognized false positive patterns
      - common-false-positives
      # std-error-handling excludes common error handling patterns that are intentional
      - std-error-handling
    
    # paths defines regex patterns for files to exclude from linting
    paths:
      # .*_ssz\.go$ excludes SSZ-generated files (Simple Serialize format)
      - .*_ssz\.go$
      # third_party$ excludes third-party code
      - third_party$
      # builtin$ excludes built-in packages
      - builtin$
      # examples$ excludes example code which may not follow all conventions
      - examples$

# Formatters configuration
# Controls which code formatters are enabled and their exclusions
formatters:
  enable:
    # gofmt is the standard Go code formatter
    - gofmt
    # gofumpt is a stricter version of gofmt with additional formatting rules
    - gofumpt
    # goimports formats code and organizes imports (adds missing, removes unused)
    - goimports
  
  # exclusions defines which files should not be auto-formatted
  exclusions:
    # generated controls how generated files are handled by formatters
    # Using lax to allow some flexibility while still maintaining basic formatting
    generated: lax
    
    # paths defines regex patterns for files to exclude from formatting
    paths:
      # .*_ssz\.go$ excludes SSZ-generated files to preserve their generated format
      - .*_ssz\.go$
      # third_party$ excludes third-party code to preserve original formatting
      - third_party$
      # builtin$ excludes built-in packages
      - builtin$
      # examples$ excludes example code
      - examples$