.golangci.yml

# Linter configuration (ADR-065, issue #457).
#
# CI verified formatting, generated artifacts, coverage, documented commands and
# live behaviour, and ran no linter at all: `gofmt -l` only, plus the small vet
# subset `go test` runs on its own. This is the class of check that had no gate.
#
# The set below is the default five plus what this project's surfaces actually
# call for. Nothing is enabled for completeness.
version: "2"

run:
  timeout: 5m
  # Live tests carry a build tag, so without this the linter silently skips the
  # whole ./tests tree -- the same blind spot that let a live test break
  # unnoticed until CI ran it.
  build-tags:
    - live

linters:
  enable:
    # bodyclose: this project makes a lot of HTTP calls, and a leaked response
    # body holds a connection until GC.
    - bodyclose
    # errorlint: the error taxonomy in ADR-011 depends on errors.As/Is working
    # through wrapped errors. A %v where %w belongs breaks classification
    # silently, and classification is what decides the exit code.
    - errorlint
    # gosec: the surfaces this project has -- file permissions on credential and
    # audit paths, TLS configuration, subprocess construction in execgit.
    - gosec
    - misspell
    # unconvert and unparam: both flag NewSafeClient(timeout string), which
    # ignored its only parameter and returned a client with no timeout.
    - unconvert
    - unparam

  settings:
    errcheck:
      # An unchecked Close on a file being written is not a style nit here: it
      # is how `bb repo archive` reported success over a truncated download.
      check-type-assertions: true
      # These are excluded because the error is captured elsewhere, not
      # because it does not matter. internal/cli/outwriter wraps stdout once at
      # the root and remembers the first write failure; cmd/bb checks it after
      # the command returns and exits non-zero. A single fmt.Fprintln cannot do
      # anything with its own error -- a command has no way to report that
      # stdout is broken -- but the process can, and does.
      #
      # Without that, `bb pr list > file` on a full disk produced truncated
      # output and exited 0: the same bug as an unchecked Close on a download.
      exclude-functions:
        - fmt.Fprint
        - fmt.Fprintf
        - fmt.Fprintln
    staticcheck:
      # Everything except the QF quickfix category.
      #
      # SA finds bugs and S finds genuine simplifications; both are kept. QF is
      # staticcheck's refactoring aid -- "this if/else chain could be a tagged
      # switch", "this selector could omit an embedded field" -- and is meant to
      # be applied from an editor, not enforced in CI. It accounted for 32 of
      # the 44 staticcheck findings here, none of which would change behaviour,
      # and taking them would have meant a large mechanical diff through files
      # this change has no other reason to touch.
      #
      # Turn it back on if the project decides those rewrites are wanted; it is
      # a preference, not a correctness question.
      # The list is golangci-lint's own default with -QF* appended. Writing
      # only ["all", "-QF*"] would silently switch on the ST style checks the
      # default excludes, which turned 44 findings into 200.
      checks:
        - all
        - -ST1000
        - -ST1003
        - -ST1016
        - -ST1020
        - -ST1021
        - -ST1022
        - -QF*

    gosec:
      excludes:
        # G304 (file inclusion via variable) fires on every path this CLI is
        # asked to read by the user, which is most of them. The trust boundary
        # is the user's own shell.
        - G304

  exclusions:
    generated: lax
    rules:
      # internal/openapi/generated and internal/models/generated are produced by
      # oapi-codegen and are not hand-maintained. ADR-065 keeps them out of the
      # coverage scope for the same reason.
      - path: internal/(openapi|models)/generated/
        linters:
          - bodyclose
          - errcheck
          - errorlint
          - gosec
          - govet
          - ineffassign
          - misspell
          - staticcheck
          - unconvert
          - unparam
          - unused
      # Build tooling writes generated artifacts -- command reference, ADR
      # pages, JSON schemas, coverage baselines -- that are committed and read
      # by everyone. G301 and G306 want 0750/0600 for them, which would be
      # wrong: a generated documentation file only its author can read is not
      # more secure, it is broken. The same checks stay on for cmd/ and
      # internal/, where they caught the MCP audit directory being created
      # world-readable.
      - path: ^tools/
        linters:
          - gosec
        text: "(G301|G306)"
      # Build tooling walks the repository it is run inside and shells out to
      # git. G703 and G122 read a path that came from a directory walk as
      # attacker-controlled taint, and G204 reads a git ref that came from the
      # workflow as an injection vector. Both describe a real shape and the
      # wrong threat model: the input is the checkout these tools were pointed
      # at, and anyone who can plant a symlink in it or set the base ref can
      # already run whatever they like in the same job. Kept on for cmd/ and
      # internal/, where the input is a user's shell and the answer differs.
      - path: ^tools/
        linters:
          - gosec
        text: "(G703|G122|G204)"
      # Test files legitimately ignore errors on setup teardown and construct
      # subprocesses and temp paths that gosec cannot distinguish from the real
      # thing.
      - path: _test\.go
        linters:
          - errcheck
          - gosec
          - unparam

formatters:
  # Deliberately empty. Formatting has one gate, `task quality:format:verify`,
  # which runs the toolchain's own gofmt over the tree.
  #
  # golangci-lint's gofmt formatter is a second implementation of the same
  # policy, built against whichever Go release the linter itself was built
  # with. The two have disagreed over a file the gofmt binary called clean,
  # with `golangci-lint fmt` unable to fix its own complaint. A check that
  # cannot be satisfied and contradicts the tool it imitates is not a gate, and
  # two homes for one policy is what ADR-065 exists to prevent.
  enable: []

issues:
  # Report everything. The defaults cap output at 3 issues per linter and 3 of
  # the same kind, which makes the total look small and stable while fixes just
  # uncover the next three -- a baseline measured against it would be wrong.
  max-issues-per-linter: 0
  max-same-issues: 0