beads/scripts/ci/complexity.sh
Julian Knutsen d530cddfa6
ci: add advisory cyclomatic complexity reporting (#6081)
* ci: add advisory cyclomatic complexity reporting (bd-7g21)

Add a pinned gocyclo report, checked-in baseline, stable-key PR diff, and opt-in guard for shipped Go code. Run the report on every PR as a non-required artifact while maintainers measure signal quality; preserve existing complexity as grandfathered debt.

Agent-Signature: unknown-model/unknown-reasoning

* test(protocol): refresh dependency removal corpus
2026-08-30 19:05:17 -07:00

172 lines
7.1 KiB
Bash
Executable file

#!/usr/bin/env bash
# Report (and optionally guard) cyclomatic complexity for production Go code.
#
# This is deliberately an opt-in experiment. It uses gocyclo when available,
# reports the functions above COMPLEXITY_THRESHOLD, and compares those
# functions with a checked-in baseline. Reporting never fails the build;
# `check` can be used by a future CI lane once the baseline is trusted.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
BASELINE="${COMPLEXITY_BASELINE:-$REPO_ROOT/engdocs/complexity-baseline.txt}"
THRESHOLD="${COMPLEXITY_THRESHOLD:-30}"
TOP="${COMPLEXITY_TOP:-50}"
TOOL="${COMPLEXITY_TOOL:-gocyclo}"
GOCYCLO_VERSION="v0.6.0"
BASE_REF="${COMPLEXITY_BASE_REF:-origin/main}"
MODE="${1:-report}"
case "$MODE" in
report|check|diff|update) ;;
*)
echo "usage: $0 [report|check|diff|update]" >&2
exit 2
;;
esac
if ! command -v "$TOOL" >/dev/null 2>&1; then
echo "complexity: $TOOL is required (install with: go install github.com/fzipp/gocyclo/cmd/gocyclo@$GOCYCLO_VERSION)" >&2
exit 2
fi
case "$THRESHOLD" in
''|*[!0-9]*) echo "complexity: COMPLEXITY_THRESHOLD must be an integer" >&2; exit 2 ;;
esac
case "$TOP" in
''|*[!0-9]*) echo "complexity: COMPLEXITY_TOP must be an integer" >&2; exit 2 ;;
esac
cd "$REPO_ROOT"
current="$(mktemp)"
filtered="$(mktemp)"
current_all="$(mktemp)"
current_all_raw="$(mktemp)"
changed="$(mktemp)"
base_scan="$(mktemp)"
base_filtered="$(mktemp)"
base_dir="$(mktemp -d)"
trap 'rm -f "$current" "$filtered" "$current_all" "$current_all_raw" "$changed" "$base_scan" "$base_filtered"; rm -rf "$base_dir"' EXIT
# Keep the analyzer's input explicit: these are shipped Go packages. backend/
# is included, while backend/conformance is excluded below. Paths are derived
# inside scan so an archived base with deleted or renamed files is handled.
# gocyclo's ignore expression is matched against source paths. The awk filter
# is a second defense for fake/custom analyzers and generated files.
scan() {
local root="$1" raw="$2" out="$3" threshold="${4:-$THRESHOLD}"
local analyzer_paths=()
while IFS= read -r path; do
analyzer_paths+=("${path#"$root/"}")
done < <(find "$root" -maxdepth 1 -type f -name '*.go' -print)
for path in cmd internal backend beadserrors format issueops journalops memoryops schema plugins integrations release-gates; do
[[ -d "$root/$path" ]] && analyzer_paths+=("$path")
done
(cd "$root" && "$TOOL" -ignore '(_test\.go$|\.gen\.go$|generated|(^|/)conformance/)' "${analyzer_paths[@]}") >"$raw"
awk -v threshold="$threshold" '$1 >= threshold && $4 !~ /_test\.go:/ && $4 !~ /\.gen\.go:/ && $4 !~ /generated/ && $4 !~ /(^|\/)backend\/conformance\// { print }' "$raw" \
| sort -k1,1nr -k2,2 -k3,3 -k4,4 >"$out"
}
scan "$REPO_ROOT" "$current" "$filtered"
if [[ "$MODE" == update ]]; then
{
echo "# Cyclomatic complexity baseline (generated by scripts/ci/complexity.sh update)"
echo "# Threshold: $THRESHOLD (only shipped production functions at or above it are tracked)"
cat "$filtered"
} >"$BASELINE"
echo "complexity: wrote $BASELINE ($(wc -l <"$filtered") functions)"
exit 0
fi
echo "Cyclomatic complexity (threshold >= $THRESHOLD; shipped production Go only)"
if [[ -s "$filtered" ]]; then
head -n "$TOP" "$filtered"
else
echo "(no functions meet threshold)"
fi
if [[ "$MODE" == diff ]]; then
if [[ -z "$BASE_REF" ]] || ! git rev-parse --verify "$BASE_REF" >/dev/null 2>&1; then
echo "complexity: diff requires an available COMPLEXITY_BASE_REF (got '$BASE_REF')" >&2
exit 2
fi
git archive "$BASE_REF" | tar -x -C "$base_dir"
# Scan the base at zero so a function crossing the threshold is reported
# as a regression rather than as an indistinguishable new function.
scan "$base_dir" "$base_scan" "$base_filtered" 0
scan "$REPO_ROOT" "$current_all_raw" "$current_all" 0
echo
echo "Complexity changes relative to $BASE_REF (stable package/function/file keys)"
awk -v threshold="$THRESHOLD" '
function keyof() { file=$4; sub(/:[0-9]+:[0-9]+$/, "", file); return $2 SUBSEP $3 SUBSEP file }
FILENAME == ARGV[1] { key=keyof(); old[key]=$1; oldline[key]=$0; next }
{ key=keyof(); now[key]=$1; line[key]=$0 }
END {
for (k in now) {
if (!(k in old) && now[k] >= threshold) print "new: " line[k]
else if (k in old && now[k] >= threshold && now[k] > old[k]) print "regressed: " line[k] " (baseline " old[k] ")"
else if (k in old && now[k] < old[k] && old[k] >= threshold) print "improved: " line[k] " (baseline " old[k] ")"
}
# Base scans include scores below the reporting threshold so a
# function crossing upward is visible. Do not print every such
# historical function as a removal; only report deletions that
# were themselves above the configured threshold.
for (k in old) if (!(k in now) && old[k] >= threshold) print "deleted: " oldline[k] " (baseline " old[k] ")"
}
' "$base_filtered" "$current_all" | sort
exit 0
fi
echo
echo "Changed functions relative to $BASE_REF (advisory; file-level scope)"
if git rev-parse --verify "$BASE_REF" >/dev/null 2>&1; then
git diff --name-only "$BASE_REF"...HEAD -- '*.go' | awk '!/_test\.go$/ && !/\.gen\.go$/ && !/generated/ && (index($0, "/") == 0 || $0 ~ /^(cmd|internal|backend|beadserrors|format|issueops|journalops|memoryops|schema|plugins|integrations|release-gates)\//) && $0 !~ /^backend\/conformance\//' >"$changed"
if [[ -s "$changed" ]]; then
awk -v top="$TOP" 'FILENAME == ARGV[1] { files[$0] = 1; next } { file = $4; sub(/:[0-9]+:[0-9]+$/, "", file); if (file in files && ++n <= top) print }' "$changed" "$filtered"
else
echo "(no shipped Go files changed)"
fi
else
echo "(base ref $BASE_REF unavailable; full report above)"
fi
if [[ ! -f "$BASELINE" ]]; then
echo "complexity: baseline not found: $BASELINE (run '$0 update')" >&2
[[ "$MODE" == check ]] && exit 1
exit 0
fi
# Compare by package, function, and file (not line number), so harmless line
# movement does not look like a new offender. A check fails only for a new
# tracked function or a regression above its baseline; report remains advisory.
regressions="$(awk '
FILENAME == ARGV[1] {
if ($1 ~ /^#/ || NF < 4) next
file = $4
sub(/:[0-9]+:[0-9]+$/, "", file)
key = $2 SUBSEP $3 SUBSEP file
baseline[key] = $1
next
}
{
file = $4
sub(/:[0-9]+:[0-9]+$/, "", file)
key = $2 SUBSEP $3 SUBSEP file
if (!(key in baseline)) {
print "new: " $0
} else if ($1 > baseline[key]) {
print "regressed: " $0 " (baseline " baseline[key] ")"
}
}
' "$BASELINE" "$filtered")"
if [[ -n "$regressions" ]]; then
echo "complexity: changes relative to baseline:" >&2
echo "$regressions" >&2
if [[ "$MODE" == check ]]; then
exit 1
fi
else
echo "complexity: no regressions relative to baseline"
fi