housekeeping: tighten linting, testing, and verification standards (#47)

* update file permissions to 0o644 in test case for consistency

* refactor: simplify and standardize mutex usage, improve error messages, and enhance code consistency

* refactor: improve code comments, rename function return values for clarity, and standardize formatting

* add comment explaining purpose of `removeIPs` function

* add `test-short` target to Makefile for running quick tests without race detection

* increase coverage target to 80% and disable informational comments in codecov config

* document `test-short` target, verification process, and acceptance criteria in CLAUDE.md

* update CI workflows: enable caching, enforce 80% coverage, and standardize job configuration

* remove unnecessary package comment in `add.go`

* update `.golangci.yml`: enable additional linters, configure settings, and improve exclusions

* update `.golangci.yml`: adjust complexity thresholds, add `argument-limit` linter, and refine exclusions

* refactor `fuzz_test.go`: extract `validateParsedHostLine` helper, replace inline validation logic, and reuse `testBaseHosts` constant for clarity and consistency

* update CLAUDE.md: document enhanced verification steps, updated complexity thresholds, and new testing rules

* update GNUmakefile: add `coverage-check` target, enforce 80% coverage, refine `verify` and `verify-full` definitions

* refactor `property_test.go`: replace manual loops with `slices.Contains`, extract `validateParsedLines` helper, and reuse `testHostsLocalhost` constant for clarity and consistency

* refactor `root_test.go`: extract `setupTestHosts` and `captureOutput` helpers, reuse constants for clarity, and replace repetitive setup logic for improved consistency

* refactor `txeh.go`: replace `"windows"` string literals with `osWindows` constant for clarity and consistency

* refactor `txeh_test.go`: replace manual loops with `slices.Contains`, extract `createTempHostsFile` helper, reuse constants for clarity, and improve test consistency

Author: cjimti

.github/workflows/ci.yml

@@ -6,24 +6,31 @@ on:
   pull_request:
     branches: [main, master]
 
-permissions:
-  contents: read
+permissions: read-all
 
 jobs:
   lint:
+    name: Lint
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
       - uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5  # v6.2.0
         with:
           go-version-file: go.mod
+          cache: true
       - uses: golangci/golangci-lint-action@1e7e51e771db61008b38414a730f564565cf7c20  # v9.2.0
         with:
-          version: latest
+          version: v2.8.0
           args: --timeout=5m
+          only-new-issues: true
 
   test:
+    name: Test
     runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest]
@@ -32,10 +39,21 @@ jobs:
       - uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5  # v6.2.0
         with:
           go-version-file: go.mod
+          cache: true
 
       - name: Run tests
         run: go test -race -coverprofile=coverage.txt -covermode=atomic ./...
 
+      - name: Check coverage threshold
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          COVERAGE=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}' | sed 's/%//')
+          echo "Total coverage: ${COVERAGE}%"
+          if [ "$(echo "$COVERAGE < 80.0" | bc)" -eq 1 ]; then
+            echo "Coverage ${COVERAGE}% is below 80% threshold"
+            exit 1
+          fi
+
       - name: Upload coverage
         if: matrix.os == 'ubuntu-latest'
         uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de  # v5.5.2
@@ -44,12 +62,16 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
 
   build:
+    name: Build
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
       - uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5  # v6.2.0
         with:
           go-version-file: go.mod
+          cache: true
 
       - name: Build
         run: go build -v ./...
@@ -58,12 +80,16 @@ jobs:
         run: go mod verify
 
   security:
+    name: Security Scan
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
       - uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5  # v6.2.0
         with:
           go-version-file: go.mod
+          cache: true
 
       - name: Run gosec
         uses: securego/gosec@424fc4cd9c82ea0fd6bee9cd49c2db2c3cc0c93f  # v2.22.11

.golangci.yml

@@ -21,11 +21,14 @@ linters:
     - durationcheck      # Detect duration multiplication issues
     - makezero           # Find slice append issues
     - wastedassign       # Find wasted assignments
+    - copyloopvar        # Loop variable copying
 
     # ===== Code Style =====
     - misspell           # Spelling mistakes
     - unconvert          # Unnecessary type conversions
     - whitespace         # Whitespace issues
+    - godot              # Comment punctuation enforcement
+    - revive             # Comprehensive style/safety rules
 
     # ===== Code Quality =====
     - gocritic           # Comprehensive checks
@@ -38,13 +41,30 @@ linters:
     - unparam            # Unused parameters
     - errname            # Error naming conventions
     - errorlint          # Error wrapping issues
+    - goconst            # Detect repeated string literals
+    - thelper            # Test helper validation
+    - modernize          # Go modernization suggestions
+
+    # ===== Security =====
+    - gosec              # Security scanning (OWASP)
+
+    # ===== Error Handling =====
+    - wrapcheck          # Ensure external package errors are wrapped
 
   settings:
+    errcheck:
+      check-type-assertions: true
+
     gocyclo:
-      min-complexity: 15
+      min-complexity: 10
 
     gocognit:
-      min-complexity: 20
+      min-complexity: 15
+
+    govet:
+      disable:
+        - fieldalignment
+        - shadow
 
     misspell:
       locale: US
@@ -53,12 +73,19 @@ linters:
       max-func-lines: 30
 
     nestif:
-      min-complexity: 6
+      min-complexity: 5
+
+    prealloc:
+      simple: true
+      range-loops: true
+      for-loops: true
 
     gocritic:
       enabled-tags:
         - diagnostic
         - performance
+        - style
+        - opinionated
       disabled-checks:
         - hugeParam
         - rangeValCopy
@@ -69,23 +96,94 @@ linters:
       asserts: true
       comparison: true
 
+    gosec:
+      excludes:
+        - G104
+      config:
+        G306: "0644"
+
+    goconst:
+      min-len: 3
+      min-occurrences: 3
+
+    wrapcheck:
+      ignore-sigs:
+        - ".Errorf("
+        - "errors.New("
+        - "errors.Unwrap("
+        - "errors.Join("
+        - ".Wrap("
+        - ".Wrapf("
+        - ".WithMessage("
+        - ".WithMessagef("
+        - ".WithStack("
+
+    revive:
+      rules:
+        # Style
+        - name: blank-imports
+        - name: context-as-argument
+        - name: dot-imports
+        - name: error-return
+        - name: error-strings
+        - name: error-naming
+        - name: exported
+          arguments:
+            - "checkPrivateReceivers"
+        - name: increment-decrement
+        - name: var-naming
+        - name: var-declaration
+        - name: package-comments
+        - name: range
+        - name: receiver-naming
+        - name: indent-error-flow
+        - name: superfluous-else
+        - name: modifies-parameter
+        - name: unreachable-code
+        - name: modifies-value-receiver
+        - name: constant-logical-expr
+        - name: bool-literal-in-expr
+        - name: redefines-builtin-id
+        - name: range-val-in-closure
+        - name: range-val-address
+        - name: waitgroup-by-value
+        - name: atomic
+        - name: call-to-gc
+        - name: duplicated-imports
+        - name: string-of-int
+        - name: defer
+          arguments:
+            - ["call-chain", "loop", "method-call", "recover", "immediate-recover", "return"]
+        - name: unconditional-recursion
+        - name: identical-branches
+        - name: unexported-naming
+        - name: unnecessary-stmt
+        - name: useless-break
+        - name: context-keys-type
+        - name: time-equal
+        - name: time-naming
+        - name: errorf
+        - name: empty-block
+        - name: get-return
+        - name: early-return
+        - name: unused-parameter
+          disabled: true
+        - name: confusing-naming
+        - name: confusing-results
+        - name: argument-limit
+          arguments:
+            - 5
+
   exclusions:
+    generated: lax
     warn-unused: true
     rules:
-      # Relax rules for tests
-      - path: _test\.go
-        linters:
-          - errcheck
-          - gocritic
-          - gocognit
-          - gocyclo
-          - unparam
-
       # Allow longer functions in cmd/
       - path: cmd/
         linters:
           - gocyclo
           - gocognit
+          - wrapcheck
 
       # Generated files
       - path: generated
@@ -96,7 +194,9 @@ formatters:
   enable:
     - gofmt
     - goimports
-
+    - gofumpt
+  exclusions:
+    generated: lax
   settings:
     goimports:
       local-prefixes:

CLAUDE.md

@@ -18,17 +18,20 @@ txeh is a Go library and CLI utility for managing /etc/hosts file entries. It pr
 
 ```bash
 # Full verification (run before every commit)
-make verify          # fmt, lint, test-unit, security, go mod verify
+make verify          # fmt, lint, test-unit, security, coverage-check, go mod verify
 
-# Extended verification
-make verify-full     # fmt, lint, test, security, go mod verify
+# Extended verification (adds dead-code analysis)
+make verify-full     # fmt, lint, test, security, coverage-check, dead-code, go mod verify
 
 # Format, lint, test individually
 make fmt             # gofmt + goimports
-make lint            # golangci-lint
+make lint            # golangci-lint (37 linters, no test relaxations)
 make test-unit       # go test -race ./...
+make test-short      # Fast tests (no race detection)
 make coverage        # Coverage report (HTML + summary)
+make coverage-check  # Enforce 80% coverage threshold
 make security        # gosec + govulncheck
+make mutate          # Mutation testing (gremlins, 60% efficacy threshold)
 ```
 
 ## Architecture
@@ -68,8 +71,9 @@ make security        # gosec + govulncheck
 ### Style
 - Follow [Google Go Style Guide](https://google.github.io/styleguide/go/)
 - All code must pass `golangci-lint` with project config
-- Maximum cyclomatic complexity: 15
-- Maximum cognitive complexity: 20
+- Maximum cyclomatic complexity: 10 per function
+- Maximum cognitive complexity: 15 per function
+- Maximum function arguments: 5
 
 ### Documentation
 - All exported functions, types, and packages require doc comments
@@ -93,10 +97,42 @@ func (h *Hosts) Save() error {
 ```
 
 ### Testing
-- Test coverage minimum: 82%
+- Test coverage minimum: 80% (CI enforced)
 - Use table-driven tests for multiple cases
 - Use `t.Parallel()` for independent tests
 - Race detection required: `go test -race ./...`
+- Property-based tests with `rapid` for invariant verification
+
+### Verification Stack
+
+All changes go through a 4-level verification process (see [AI-Verified Development](https://imti.co/ai-verified-development/)):
+
+1. **Static analysis** - `make lint` runs golangci-lint with 37 linters. Runs in seconds, catches type errors, complexity violations, security anti-patterns.
+2. **Unit tests** - `make test-unit` runs with `-race`. Coverage gate at 80%. `make coverage-check` enforces this locally.
+3. **Integration/E2E tests** - Tagged test suites (`-tags=integration`, `-tags=e2e`) for system-level validation.
+4. **Mutation testing** - `make mutate` runs gremlins with a 60% efficacy threshold. Validates that tests catch real bugs, not just exercise code.
+
+Do not review AI code until every level passes. `make verify` runs levels 1-2 plus security. `make verify-full` adds dead-code analysis.
+
+### Acceptance Criteria
+
+Define specs as Given/When/Then assertions before writing code. Each "then" becomes a concrete test with a hardcoded expected value.
+
+```
+Given a hosts file with "127.0.0.1 myhost"
+When RemoveHost("myhost") is called
+Then ListHostsByIP("127.0.0.1") returns an empty list
+```
+
+Write the test first, confirm it fails, then implement.
+
+### AI-Specific Rules
+
+- **No tautological tests.** Tests must encode specific expected outputs as hardcoded values. Never reimplement function logic inside assertions.
+- **No hallucinated imports.** Verify every dependency exists and is actively maintained before adding it.
+- **Human review required.** A human must review and approve every line of code before commit.
+- **Non-obvious decisions require comments.** If a choice isn't self-evident, explain why in a comment or commit message.
+- **Dead code detection.** Run `make dead-code` to remove untested utilities. Unreachable code is a sign of tautological tests.
 
 ## Security Requirements
 
@@ -148,10 +184,10 @@ make lint-fix       # Run golangci-lint with auto-fix
 make fmt            # Format code (gofmt + goimports)
 
 # Before committing
-make verify         # fmt, lint, test-unit, security, go mod verify
+make verify         # fmt, lint, test-unit, security, coverage-check, go mod verify
 
 # Extended verification
-make verify-full    # fmt, lint, test, security, go mod verify
+make verify-full    # fmt, lint, test, security, coverage-check, dead-code, go mod verify
 
 # Testing
 make test-integration  # Integration tests (tagged)