.golangci.yml

# golangci-lint v2 configuration
# This config is used by both standard golangci-lint and custom builds with plugins.
#
# Custom Linters (Module Plugins):
# - Custom linters are defined in .custom-gcl.yml and built into a custom binary
# - The custom binary (custom-gcl) contains ALL standard linters + custom plugins
# - Enable custom linters here in the 'enable' list (e.g., 'lintroller')
# - Configure custom linters in 'settings.custom.<linter-name>' section below
#
# To add a new custom linter:
# 1. Add plugin to .custom-gcl.yml
# 2. Run `golangci-lint custom` to build custom-gcl binary
# 3. Enable the linter in the 'enable' list below
# 4. Configure it in 'settings.custom.<linter-name>' section
#
# References:
# - Configuration docs: https://golangci-lint.run/docs/linters/configuration/
# - Module plugins: https://golangci-lint.run/docs/plugins/module-plugins/

version: "2"
run:
  tests: true
  # golangci-lint takes a machine-global single-instance lock. Parallel
  # worktree sessions (and pre-commit hooks racing manual runs) otherwise fail
  # with "parallel golangci-lint is running"; serializing makes the second
  # instance wait instead.
  allow-serial-runners: true
linters:
  enable:
    - bodyclose
    - cyclop
    - depguard  # Controls allowed/forbidden package imports
    - dogsled
    - dupl
    - err113
    - errorlint  # Detects %v instead of %w in fmt.Errorf, errors.Is/errors.As usage
    - forbidigo
    - funlen
    - gocognit
    - gocritic
    - godot
    - gosec
    - importas
    - lintroller  # Custom plugin: Atmos-specific test rules (see settings.custom.lintroller)
    - loggercheck
    - misspell
    - nestif
    - nilerr
    - nolintlint
    - revive
    - rowserrcheck
    - tparallel
    - unconvert
    - unparam
    - unused
    - whitespace
  settings:
    cyclop:
      max-complexity: 15
    depguard:
      rules:
        # Auth Architecture: Provider-Agnostic Core
        # Core auth packages must remain provider-agnostic.
        # Provider-specific code belongs in pkg/auth/providers/, pkg/auth/identities/, or pkg/auth/cloud/.
        provider-agnostic-auth:
          files:
            - "$all"
            - "!**/pkg/auth/providers/**"
            - "!**/pkg/auth/identities/**"
            - "!**/pkg/auth/cloud/**"
            - "!**/pkg/auth/factory/**"
            # pkg/store is the cloud-backend storage layer (SSM, Secrets Manager, Vault,
            # Azure Key Vault, GCP Secret Manager); it legitimately uses cloud SDKs and is
            # not provider-agnostic auth code.
            - "!**/pkg/store/**"
            - "!**/pkg/auth/types/aws_credentials.go"
            - "!**/pkg/auth/types/github_oidc_credentials.go"
            - "!**/pkg/ai/**"
            - "!**/internal/aws_utils/**"
            - "!**/pkg/aws/identity/**"
            - "!**/pkg/aws/organization/**"
            - "!**/pkg/aws/security/**"
            - "!**/pkg/provisioner/backend/**"
            - "!**/pkg/ci/github/**"
            - "!**/pkg/ci/providers/github/**"
            - "!**/pkg/ci/planfile/github/**"
            - "!**/pkg/ci/planfile/s3/**"
            - "!**/pkg/github/**"
            - "$test"
          deny:
            # AWS: Identity and auth-related SDKs
            - pkg: "github.com/aws/aws-sdk-go-v2"
              desc: "AWS SDK imports forbidden in provider-agnostic auth code; use pkg/auth/providers/aws/, pkg/auth/identities/aws/, or pkg/auth/cloud/aws/ for AWS-specific implementations"
            # Azure: Identity and auth SDKs (Entra ID, Azure AD)
            - pkg: "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
              desc: "Azure Identity SDK imports forbidden in provider-agnostic auth code; use pkg/auth/providers/azure/ or pkg/auth/identities/azure/ for Azure-specific implementations"
            - pkg: "github.com/AzureAD"
              desc: "Azure AD SDK imports forbidden in provider-agnostic auth code; use pkg/auth/providers/azure/ or pkg/auth/identities/azure/ for Azure-specific implementations"
            # GCP: Identity and auth SDKs
            - pkg: "cloud.google.com/go/iam"
              desc: "GCP IAM SDK imports forbidden in provider-agnostic auth code; use pkg/auth/providers/gcp/ or pkg/auth/identities/gcp/ for GCP-specific implementations"
            - pkg: "google.golang.org/api/iam"
              desc: "GCP IAM API imports forbidden in provider-agnostic auth code; use pkg/auth/providers/gcp/ or pkg/auth/identities/gcp/ for GCP-specific implementations"
            - pkg: "google.golang.org/api/iamcredentials"
              desc: "GCP IAM Credentials API imports forbidden in provider-agnostic auth code; use pkg/auth/providers/gcp/ or pkg/auth/identities/gcp/ for GCP-specific implementations"
            # GitHub: Identity SDKs
            - pkg: "github.com/google/go-github"
              desc: "GitHub SDK imports forbidden in provider-agnostic auth code; use pkg/auth/providers/github/ for GitHub-specific implementations"
    dogsled:
      max-blank-identifiers: 3
    dupl:
      threshold: 150
    errorlint:
      # Check for non-wrapping format verbs (%v) in fmt.Errorf calls.
      # Enforces using %w to properly wrap errors for errors.Is/errors.As.
      errorf: true
      # Check whether fmt.Errorf uses the %w verb for formatting errors.
      # Note: supports multiple %w verbs per fmt.Errorf call (requires Go 1.20+).
      errorf-multi: true
      # Check for plain type assertions and suggest replacing them with errors.As.
      asserts: true
      # Check for plain error comparisons and suggest replacing them with errors.Is.
      comparison: true
    forbidigo:
      forbid:
        - pattern: os\.Getenv
          msg: Use `viper.BindEnv` for new environment variables instead of `os.Getenv`
        - pattern: os\.UserHomeDir
          msg: Use `homedir.Dir()` from `github.com/cloudposse/atmos/pkg/config/homedir` instead of `os.UserHomeDir()` for better cross-platform support, caching, and OS-specific methods
        - pattern: '\.(Skip|SkipNow)\('
          msg: Use `t.Skipf("<reason>")` with a descriptive reason; do not use `t.Skip`/`t.SkipNow`
        - pattern: ^path\.Join$
          msg: Use `filepath.Join` for OS-appropriate path separators instead of `path.Join` (which always uses forward slashes)
        - pattern: 'WithHint\((?:[^()]|\((?:[^()]|\([^()]*\))*\))*?,\s*fmt\.Sprintf'
          msg: Use `WithHintf()` instead of `WithHint(err, fmt.Sprintf(...))` for formatted hint messages
        - pattern: term\.IsTerminal\(
          msg: Use `term.IsTTYSupportForStdout()`, `term.IsTTYSupportForStderr()`, or `term.IsTTYSupportForStdin()` instead of `term.IsTerminal()` for consistent and mockable TTY detection
        - pattern: 'fmt\.Errorf\("(?:[^"%]|%[^w])*"\s*\)'
          msg: "Use static sentinel errors from errors/errors.go instead of dynamic errors; wrap with fmt.Errorf(\"%w: context\", ErrSentinel) if context needed"
        - pattern: 'errors\.New\(fmt\.Sprintf'
          msg: "Use static sentinel errors from errors/errors.go instead of errors.New(fmt.Sprintf(...)); use fmt.Errorf(\"%w: ...\", ErrSentinel) for context"
        - pattern: 'github\.com/pkg/errors'
          msg: "Do not use deprecated github.com/pkg/errors; use static sentinel errors from errors/errors.go instead"
        - pattern: '\bpkgerrors\.'
          msg: "Do not use deprecated pkg/errors; use static sentinel errors from errors/errors.go instead"
        - pattern: 'assert\.Contains\(.*,\s*err\.Error\('
          msg: "NEVER use string matching on errors; use assert.ErrorIs(err, sentinel) to check sentinel errors from errors/errors.go"
        - pattern: 'strings\.Contains\(err\.Error\('
          msg: "NEVER use string matching on errors; use errors.Is(err, sentinel) to check sentinel errors from errors/errors.go"
        - pattern: github\.com/golang/mock
          msg: Use `go.uber.org/mock` instead of archived `github.com/golang/mock`
        - pattern: github\.com/mitchellh/go-homedir
          msg: Use `github.com/cloudposse/atmos/pkg/config/homedir` (our forked version) instead of `github.com/mitchellh/go-homedir`
        - pattern: log\.Info\(.*[Dd][Ee][Bb][Uu][Gg]
          msg: Use `log.Debug()` for debug messages instead of `log.Info()` with "DEBUG" in the message
        - pattern: log\.Warn\(.*[Dd][Ee][Bb][Uu][Gg]
          msg: Use `log.Debug()` for debug messages instead of `log.Warn()` with "DEBUG" in the message
        - pattern: log\.Error\(.*[Dd][Ee][Bb][Uu][Gg]
          msg: Use `log.Debug()` for debug messages instead of `log.Error()` with "DEBUG" in the message
        - pattern: '^fmt\.Print(f|ln)?$'
          msg: Use Atmos output helpers (`data.Write*` for stdout, `ui.Write*` for stderr) instead of direct `fmt.Print*` output
        - pattern: 'fmt\.Fprint(f|ln)?\(\s*os\.(Stdout|Stderr)'
          msg: Use Atmos output helpers (`data.Write*`/`ui.Write*`) or `iolib.Data`/`iolib.UI` instead of writing directly to `os.Stdout` or `os.Stderr`
        # Flag Binding Protection: ENFORCED
        # pkg/flags/ infrastructure is fully implemented - these patterns are now banned outside pkg/flags/.
        - pattern: viper\.BindEnv\(
          msg: NEVER call viper.BindEnv() directly - use pkg/flags/ unified flag parser (consult flag-handler agent)
        - pattern: viper\.BindPFlag\(
          msg: NEVER call viper.BindPFlag() directly - use pkg/flags/ unified flag parser (consult flag-handler agent)
      exclude-godoc-examples: false
      analyze-types: true
    funlen:
      lines: 60
      statements: 40
      ignore-comments: true
    gocognit:
      min-complexity: 20
    gocritic:
      enabled-checks:
        - rangeValCopy
        - hugeParam
        - commentedOutCode
        - emptyDecl
        - filepathJoin
        - commentedOutImport
        - initClause
        - nestingReduce
        - preferFilepathJoin
    godot:
      capital: true
      period: true
    gosec:
      excludes:
        - G101
    importas:
      alias:
        - pkg: github.com/cloudposse/atmos/pkg/logger
          alias: log
      no-unaliased: true
      no-extra-aliases: false
    # Custom linter configurations (module plugins)
    # These settings only apply when using the custom-gcl binary built via `golangci-lint custom`.
    # Standard golangci-lint binary will not have these linters available.
    #
    # Each custom linter must:
    # - Be listed in .custom-gcl.yml plugins section
    # - Be enabled in the linters.enable list above
    # - Have type: "module" specified here
    # - Implement the golangci-lint plugin interface
    #
    # To add a new custom linter configuration:
    # Add a new section here with your linter's name and settings.
    custom:
      lintroller:
        type: "module"  # Required: indicates this is a module plugin (not Go .so plugin)
        description: "Atmos project-specific linting rules (t.Setenv/os.Setenv/os.MkdirTemp/perf.Track checks)"
        settings:
          # These settings are passed to the plugin's Settings struct (see tools/lintroller/plugin.go)
          # Each rule can be independently enabled/disabled
          tsetenv-in-defer: true      # Detects t.Setenv called inside defer blocks (use os.Setenv in defer instead)
          os-setenv-in-test: true     # Detects os.Setenv in test files (use t.Setenv instead for auto cleanup)
          os-mkdirtemp-in-test: true  # Detects os.MkdirTemp in test files (use t.TempDir instead for auto cleanup)
          perf-track: true            # Detects missing defer perf.Track() in public functions per coding guidelines (see excludedPackages/excludedReceivers in rule_perf_track.go)

      # Example: Add another custom linter configuration
      # another-linter:
      #   type: "module"
      #   description: "Another custom linter"
      #   settings:
      #     some-rule: true
    lll:
      line-length: 120
      tab-width: 4
    loggercheck:
      kitlog: false
      klog: false
      logr: false
      slog: false
      zap: false
      require-string-key: true
      no-printf-like: true
      rules:
        - (github.com/cloudposse/atmos/pkg/logger.AtmosLogger).Info
        - (github.com/cloudposse/atmos/pkg/logger.AtmosLogger).Error
        - (github.com/cloudposse/atmos/pkg/logger.AtmosLogger).Warn
        - (github.com/cloudposse/atmos/pkg/logger.AtmosLogger).Debug
        - (github.com/cloudposse/atmos/pkg/logger.AtmosLogger).Fatal
        - (github.com/cloudposse/atmos/pkg/logger.AtmosLogger).Trace
    nestif:
      min-complexity: 4
    revive:
      rules:
        - name: banned-characters
          arguments:
            - goto
        - name: error-strings
          arguments:
            - disallow-newlines: true
        - name: file-length-limit
          arguments:
            - max: 500
              skipBlankLines: true
              skipComments: true
        - name: function-length
          arguments:
            - 50
            - 60
        - name: function-result-limit
          arguments:
            - 3
        - name: cognitive-complexity
          arguments:
            - 25
        - name: cyclomatic
          arguments:
            - 10
        - name: add-constant
          arguments:
            - allowFloats: 0.0,0.,1.0,1.,2.0,2.
              allowInts: 0,1,2,3,4
              allowStrs: '"","image","error","path","import","path","%w","%s","file","/"'
              maxLitCount: "3"
        - name: argument-limit
          arguments:
            - 5
        - name: deep-exit
        - name: early-return
        - name: comment-spacings
          arguments:
            - mypragma
            - otherpragma
          disabled: false
        - name: var-declaration
  exclusions:
    generated: lax
    presets:
      - comments
      - common-false-positives
      - legacy
      - std-error-handling
    rules:
      - linters:
          - godot
        path: mock_.*\.go$
      - linters:
          - err113
          - errcheck
          - forbidigo
          - funlen
          - gocognit
          - gosec
          - revive
        path: _test\.go$
      - linters:
          - cyclop
        path: (.+)_test\.go
      # Allow fmt.Errorf when wrapping static errors from errUtils package
      - linters:
          - err113
        source: 'fmt\.Errorf\("%w: .+", errUtils\.'
      # Allow fmt.Errorf when wrapping any static Err* variable
      - linters:
          - err113
        source: 'fmt\.Errorf\("%w: .+", Err[A-Z]'
      # Allow errors.Join with fmt.Errorf for converting strings to errors
      - linters:
          - err113
        path: ".*"
        source: 'errors\.Join\(.*errUtils\..*fmt\.Errorf'
# Allow viper.BindEnv and viper.BindPFlag in pkg/flags/ and test files
      - linters:
          - forbidigo
        path: ^pkg/flags/
        text: "viper\\.BindEnv|viper\\.BindPFlag"
      - linters:
          - forbidigo
        path: _test\.go$
        text: "viper\\.BindEnv|viper\\.BindPFlag"
      # Legacy direct process output. New production code should use the Atmos
      # I/O layer so stdout/stderr routing and masking stay consistent.
      - linters:
          - forbidigo
        path: ^(cmd/auth/(env|list)\.go|cmd/cmd_utils\.go|cmd/devcontainer/helpers\.go|cmd/docs\.go|cmd/profile/(list|show)\.go|cmd/version/formatters\.go|internal/exec/(atmos|workflow_utils)\.go|pkg/ai/(context\.go|session/manager\.go|tools/permission/prompter\.go)|pkg/auth/(cloud/kube/config\.go|credentials/store\.go|identities/aws/webflow_ui\.go|providers/aws/sso\.go|providers/azure/device_code_ui\.go)|pkg/ci/providers/generic/provider\.go|pkg/devcontainer/(lifecycle_config|lifecycle_list)\.go|pkg/env/output\.go|pkg/pager/pager\.go|pkg/terminal/terminal\.go|pkg/ui/markdown/codeblock\.go|pkg/utils/version_utils\.go|tools/gomodcheck/main\.go)$
        text: "Atmos output helpers|direct `fmt\\.Print\\*` output|writing directly to `os\\.Stdout` or `os\\.Stderr`"
      - linters:
          - forbidigo
        path: ^tests/testhelpers/fake_container_runtime\.go$
        text: "Atmos output helpers|direct `fmt\\.Print\\*` output|writing directly to `os\\.Stdout` or `os\\.Stderr`"
      # These files are temporarily over the 500-line limit due to terraform caching refactoring.
      # TODO: Refactor these files to reduce their size.
      - linters:
          - revive
        path: internal/exec/terraform\.go$
        text: "file-length-limit"
      - linters:
          - revive
        path: internal/exec/terraform_clean\.go$
        text: "file-length-limit"
      # schema.go is a core configuration struct file that's expected to be large.
      - linters:
          - revive
        path: pkg/schema/schema\.go$
        text: "file-length-limit"
      # handlers.go is temporarily over the 500-line limit; pre-existed at 915 lines.
      # TODO: Refactor by splitting command-specific handlers into separate files
      # (plan_handlers.go, apply_handlers.go, deploy_handlers.go).
      - linters:
          - revive
        path: pkg/ci/plugins/terraform/handlers\.go$
        text: "file-length-limit"
      # Allow os.Getenv in pkg/ci/ for reading CI platform environment variables at runtime.
      # These are not Atmos configuration - they are CI platform environment detection.
      - linters:
          - forbidigo
        path: ^pkg/ci/
        text: "os\\.Getenv"
      # Allow os.Getenv in cmd/terraform/planfile/ for CI detection.
      - linters:
          - forbidigo
        path: ^cmd/terraform/planfile/
        text: "os\\.Getenv"
    paths:
      - experiments/.*
      - third_party$
      - builtin$
      - examples$
issues:
  max-issues-per-linter: 0
  max-same-issues: 0

severity:
  default: error
  rules:
    - linters:
        - revive
      text: "cognitive-complexity|cyclomatic|function-length|function-result-limit|comment-spacings"
      severity: warning
    - linters:
        - nestif
        - nolintlint
        - gocognit
      severity: warning
    - linters:
        - gocritic
      text: "hugeParam.*Init|hugeParam.*Update|hugeParam.*View"
      severity: warning
    - linters:
        - gosec
      text: "G204"
      path: "pkg/container/.*\\.go$"
      severity: warning
    - linters:
        - gosec
      text: "G204"
      path: "pkg/devcontainer/.*\\.go$"
      severity: warning
formatters:
  enable:
    - gofumpt
    - goimports
  exclusions:
    generated: lax
    paths:
      - experiments/.*
      - third_party$
      - builtin$
      - examples$
      - _test\.go$