`8159bf2`

lint: lint-unused script + CI step to block shim regrowth (SR2 M1)

scripts/lint-unused.sh fails the build when any non-test Go file
under internal/ or cmd/ carries 'var _ = symbol' (the dead-code
shim shape). Allows the legitimate 'var _ Type = (*X)(nil)'
interface-assertion pattern by anchoring the regex to '= [A-Za-z]'
without a type name in between.

Wired into:
- Makefile 'lint-unused' target + the 'ci' alias
- .github/workflows/ci.yml as a dedicated step (the rest of the
bash lints are still local-only; lint-unused gets first-class CI
treatment because the audit caught regrowth twice in 3 days).

Authored by

espadonne 3 days ago

SHA: 8159bf2172d02beb14ab616ebce42c048226e26f
Parents: a73b2e2
Tree: e7e4f58

3 changed files

Status	File	+	-
M	`.github/workflows/ci.yml`	5	0
M	`Makefile`	5	2
A	`scripts/lint-unused.sh`	62	0

.github/workflows/ci.ymlmodified

            version: latest
            args: --timeout=5m
 +      - name: Lint — unused (no var-_-equals-symbol shims)
 +        # Block the dead-code 'silence unused import' shims that
 +        # accumulated during S00–S40 refactors (audit 2026-05-10 M1).
 +        run: scripts/lint-unused.sh
++
        - name: Test
          run: go test -trimpath ./...

Makefilemodified

  # Targets mirror what CI runs. The Makefile is the source of truth.
  .DEFAULT_GOAL := help
 -.PHONY: help dev build test test-race lint lint-policy lint-markdown lint-secret-logs lint-spdx verify-api-docs fmt tidy clean ci assets install-tools version deploy deploy-check restore-drill bench-staging docs docs-serve docs-verify gen-third-party-notices audit-a11y audit-a11y-pa11y audit-a11y-axe load-test
 +.PHONY: help dev build test test-race lint lint-policy lint-markdown lint-secret-logs lint-spdx lint-unused verify-api-docs fmt tidy clean ci assets install-tools version deploy deploy-check restore-drill bench-staging docs docs-serve docs-verify gen-third-party-notices audit-a11y audit-a11y-pa11y audit-a11y-axe load-test
  # Build metadata embedded into the binary via -ldflags.
  VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
  		echo "warn: .refs/primer-css/dist not found; run 'git clone https://github.com/primer/css .refs/primer-css' first"; \
  	fi
 -ci: lint lint-policy lint-markdown lint-secret-logs lint-spdx verify-api-docs test build ## Full CI pipeline (matches .github/workflows/ci.yml).
 +ci: lint lint-policy lint-markdown lint-secret-logs lint-spdx lint-unused verify-api-docs test build ## Full CI pipeline (matches .github/workflows/ci.yml).
  	@echo "ci: ok"
  lint-policy: ## Enforce policy-package boundary (no inline auth checks in handlers/git/cmd).
  lint-spdx: ## Verify every Go + shell source carries the SPDX license header.
  	@scripts/verify-spdx-headers.sh
 +lint-unused: ## Fail when source carries dead-code 'silence unused import' shims (var _ = symbol).
 +	@scripts/lint-unused.sh
++
  verify-api-docs: ## Fail when an /api/v1 route in code is missing from docs/public/api/.
  	@scripts/verify-api-docs.sh

scripts/lint-unused.shadded

 +#!/usr/bin/env bash
 +# SPDX-License-Identifier: AGPL-3.0-or-later
 +#
 +# Fail when any Go source file carries `var _ = <symbol>` "silence
 +# unused import" shims. The pattern accumulated during S00–S40
 +# refactors (audit 2026-05-08 found 3 instances; audit 2026-05-10
 +# found 8 — the same shape kept growing because nothing failed CI
 +# on it).
 +#
 +# False positives:
 +# - Test files use `var _ = ...` interface assertions legitimately
 +#   (e.g. `var _ http.Handler = (*X)(nil)`); we exclude *_test.go.
 +# - Genuine type contracts of the form `var _ TypeName = (*X)(nil)`
 +#   are useful and explicitly allowed by the grep below — we only
 +#   match the `var _ = SOMETHING` (no type) form, which is the
 +#   shim shape.
 +#
 +# Allowlist: rare cases where a true contract assertion happens
 +# to take this exact shape. Add a path here and explain WHY in a
 +# comment if you really need an exception.
++
 +set -euo pipefail
++
 +ALLOWED_FILES=(
 +  # (none currently)
 +)
++
 +cd "$(git rev-parse --show-toplevel)"
++
 +# Match: `var _ = <ident>` at line start, possibly indented.
 +# Reject: `var _ Type = ...` (the legitimate interface-assertion form).
 +matches=$(grep -rE '^[[:space:]]*var _ = [A-Za-z]' \
 +  --include='*.go' \
 +  --exclude='*_test.go' \
 +  --exclude-dir='vendor' \
 +  --exclude-dir='.git' \
 +  internal/ cmd/ 2>/dev/null || true)
++
 +if [ -z "$matches" ]; then
 +  echo "lint-unused: ok"
 +  exit 0
 +fi
++
 +# Strip allowlisted files.
 +for allowed in "${ALLOWED_FILES[@]}"; do
 +  matches=$(echo "$matches" | grep -v "^${allowed}:" || true)
 +done
++
 +if [ -z "$matches" ]; then
 +  echo "lint-unused: ok (allowlisted hits skipped)"
 +  exit 0
 +fi
++
 +echo "lint-unused: dead-code 'silence unused import' shims found:" >&2
 +echo >&2
 +echo "$matches" >&2
 +echo >&2
 +echo "Drop the line and the import it was silencing. If the import is" >&2
 +echo "still needed, the shim was lying — investigate the actual usage." >&2
 +echo "If you need to keep one for a legitimate reason, allowlist it in" >&2
 +echo "scripts/lint-unused.sh with a comment explaining why." >&2
 +exit 1