initial commit

.golangci.yml

@@ -0,0 +1,275 @@
+# golangci-lint configuration.
+#
+# The enabled set is chosen for signal, not coverage. A linter that fires on
+# stylistic preferences nobody agreed to trains the team to ignore the output, which
+# costs more than the findings are worth. Every linter here catches a class of bug
+# or a readability problem we actually care about; the exclusions below are
+# deliberate and commented.
+version: "2"
+
+run:
+  timeout: 5m
+  # Tests are linted. A lint failure in a test is a lint failure.
+  tests: true
+  build-tags: []
+  modules-download-mode: readonly
+  issues-exit-code: 1
+
+formatters:
+  enable:
+    - gofmt
+    - goimports
+    - gci
+  settings:
+    gci:
+      sections:
+        - standard
+        - default
+        - prefix(github.com/urpi/go-bananas)
+      no-lex-order: true
+    goimports:
+      local-prefixes: [github.com/urpi/go-bananas]
+
+linters:
+  enable:
+    # --- correctness -------------------------------------------------------
+    - errcheck        # an unchecked error is a bug waiting for a bad day
+    - govet
+    - ineffassign
+    - staticcheck     # the staticcheck suite, at its default strictness
+    - unused
+    - bodyclose       # an unclosed response body leaks a connection
+    - rowserrcheck    # a rows.Err() not checked hides a mid-iteration failure
+    - sqlclosecheck
+    - noctx           # an HTTP request without a context cannot be cancelled
+    - contextcheck    # a context stored in a struct cannot be cancelled
+    - errorlint       # %w and errors.Is, so wrapping and matching actually work
+    - nilerr          # returning nil after checking err != nil is almost always wrong
+
+    # --- readability -------------------------------------------------------
+    - revive          # exported comments, naming, control-flow clarity
+    - goconst         # a repeated literal is a constant waiting to be named
+    - godot           # comments end in a period
+    - misspell        # a typo in a comment is a typo a reader will trust
+    - unconvert
+    - prealloc
+    - whitespace
+    - nolintlint      # a nolint that no longer applies is misleading
+    - copyloopvar     # Go 1.22+ loop variables; the old idiom is now a bug
+
+    # --- security ----------------------------------------------------------
+    - gosec           # integer overflows, weak randomness, unsafe, etc.
+
+    # --- testing -----------------------------------------------------------
+    - thelper         # t.Helper() in a test helper
+    - tparallel       # a parallel test that does not call t.Parallel
+
+  settings:
+    errcheck:
+      # A type assertion or conversion that cannot fail needs no check.
+      check-type-assertions: false
+      # A blank assignment to an error is a deliberate, documented decision, not an
+      # oversight, so errcheck is asked to flag it too. The ones that remain are
+      # marked with an explicit nolint and a reason.
+      check-blank: true
+      exclude-functions:
+        # Writing to an http.ResponseWriter returns an error only when the client has
+        # gone away, and there is nothing a handler can do about that: the response
+        # is already committed and the connection is already being torn down.
+        - (net/http.ResponseWriter).Write
+        - (net/http.ResponseWriter).WriteHeader
+        # A Rollback after a successful Commit is expected to report
+        # sql.ErrTxDone, and a Rollback on the error path is immediately followed by
+        # returning that error. Checking either produces a branch that can only ever
+        # discard a result.
+        - (*database/sql.Tx).Rollback
+        # Deferred Close on a read-only database handle: the only error it can
+        # report is already lost by the time the process exits.
+        - (*database/sql.Rows).Close
+        - (io.Closer).Close
+        - (*os.File).Close
+        - (*bytes.Buffer).Write
+        - (*bytes.Buffer).WriteByte
+        - (*bytes.Buffer).WriteString
+        - (io.Writer).Write
+        - (hash.Hash).Write
+        - fmt.Fprintf
+        - fmt.Fprint
+        - fmt.Fprintln
+        - fmt.Print
+        - fmt.Println
+        - fmt.Sprintf
+        - sort.Slice
+
+    govet:
+      enable-all: true
+      disable:
+        # Field alignment is a micro-optimisation that makes every struct
+        # declaration a puzzle. It is not worth the readability cost.
+        - fieldalignment
+        # The shadow linter fires on ordinary, readable `err :=` inside an if.
+        - shadow
+
+    revive:
+      rules:
+        # requireDoc is deliberately not set. Every exported item in this codebase
+        # carries a doc comment by convention and by review, but the rule's argument
+        # name is not "requireDoc" in this version of revive, so setting it disables
+        # the whole revive rule set with a configuration error rather than enforcing
+        # anything.
+        - name: exported
+          arguments:
+            - checkPrivateReceivers
+        - name: package-comments
+        - name: blank-imports
+        - name: context-as-argument
+        - name: context-keys-type
+        - name: dot-imports
+        - name: error-return
+        # No arguments: the rule takes none. Passing "error-strings" as an argument
+        # makes revive look for a custom function of that name, fails to find it, and
+        # then silently disables the rule along with every other revive rule.
+        - name: error-strings
+        - name: error-naming
+        - name: increment-decrement
+        # The allowlist has to be a slice. Given as a bare string it is a
+        # configuration error, which stops every revive rule from loading rather
+        # than enabling this one.
+        - name: var-naming
+          arguments:
+            - [ID, VM, HTTP, URL, API, TLS, CSS, JSON, SQL, UUID, OIDC, ACL, CPU, RAM, WAC]
+        - name: receiver-naming
+        - name: indent-error-flow
+        - name: range
+        - name: unreachable-code
+        - name: redefines-builtin-id
+
+    goconst:
+      min-len: 3
+      # Raised from 4 to 6, and the wire vocabulary below is exempted. The strings
+      # that repeat in this codebase are JSON field names ("status", "version",
+      # "slug"), theme token vocabulary ("primary-hover", "normal") and the auth
+      # method "anonymous". Those are the wire and CSS contract rather than repeated
+      # logic, and hoisting them into Go constants would make them less greppable
+      # without changing anything the compiler checks.
+      min-occurrences: 6
+      ignore-string-values:
+        - anonymous
+        - none
+        - normal
+        - primary
+        - primary-hover
+        - focus-ring
+        - link
+        - version
+        - status
+        - slug
+        - items
+        - must not be empty
+      # Test data legitimately repeats literals like "200" and "published".
+      ignore-tests: true
+
+    godot:
+      scope: declarations
+      capital: false
+
+    gosec:
+      excludes:
+        # G304: a file path from configuration is intentional. The path comes from
+        # the operator's own configuration, not from a request.
+        - G304
+      # Everything gosec ships is enabled by default; only the exclusions above
+      # narrow it. G115 (integer overflow) is intentionally left on: it fires on
+      # the token engine's length arithmetic, and the two or three places that
+      # could genuinely overflow carry an explicit nolint with a reason.
+
+    staticcheck:
+      checks:
+        - all
+        # SA1019: deprecation notices for dependencies we control the version of.
+        - -SA1019
+
+    misspell:
+      # US, deliberately, and this is a real decision rather than a default.
+      #
+      # misspell's locale setting makes it *require* one dialect. With UK it
+      # rewrites the checker's idea of a correct word, which means it flags every
+      # occurrence of the US spelling -- including identifiers that are part of the
+      # published API contract: the JSON error code "unauthorized", the CSS custom
+      # property and colour-scheme vocabulary, the OpenAPI document.
+      #
+      # The codebase writes prose in British English, which misspell has nothing to
+      # say about under a US locale (it only corrects genuine misspellings, it does
+      # not enforce a dialect). So: British prose, US locale, and no linter
+      # pressure to rename a wire-format string.
+      locale: US
+      # misspell enforces one dialect even under a locale setting, so every British
+      # spelling in the prose has to be listed explicitly. This keeps the check
+      # worth having -- a genuine typo in a comment is still caught -- while
+      # accepting the dialect the documentation is written in.
+      #
+      # No identifier is in this list: exported names and JSON keys are American
+      # throughout, because they are wire and API surface rather than prose. Only
+      # comments, documentation and doc strings use the British forms.
+      ignore-rules:
+        - artefact
+        - artefacts
+        - authorises
+        - behaviour
+        - cancelled
+        - colour
+        - colours
+        - defence
+        - honoured
+        - honouring
+        - honours
+        - initialise
+        - licence
+        - localise
+        - marshalled
+        - materialise
+        - materialises
+        - materialising
+        - maximises
+        - modelled
+        - neutralises
+        - recognised
+        - recognises
+        - sanitise
+        - sanitised
+        - sanitising
+        - serialise
+        - serialised
+        - serialises
+        - summarises
+
+  exclusions:
+    generated: lax
+    presets:
+      - comments
+      - common-false-positives
+      - legacy
+      - std-error-handling
+    rules:
+      # A test function legitimately ignores the error from a deliberate failure.
+      - path: _test\.go
+        linters:
+          - gosec
+          - errcheck
+      # The SQL query constants and their arguments are checked by the store tests,
+      # which assert on behaviour rather than on the statement text.
+      - path: internal/store/
+        linters:
+          - goconst
+    paths:
+      - third_party$
+      - builtin$
+      - examples$
+
+issues:
+  # 0 disables the cap. A linter that stops reporting after 50 findings is worse
+  # than one that reports everything, because the tail is where the surprises are.
+  max-issues-per-linter: 0
+  max-same-issues: 0
+  new: false
+  fix: false