ci: per-file line-count gate (FILE_LOC_MAX)

Adds scripts/check-file-size.sh, a third lint-lane gate alongside
check-complexity.sh (CCN) and check-duplication.sh (CPD). Counts
physical lines via wc -l for every .cpp/.hpp under src/ and fails if
any file exceeds FILE_LOC_MAX.

FILE_LOC_MAX defaults to 2700, just above the current worst offender
(webserver.cpp at 2673), so CI stays green on landing. Long-term target
is 500 lines — matches the per-module SLOC ceiling used by the sibling
project under ../artistai and the natural break point where everything
else already complies. The script header lists the seven current
offenders and documents the ratchet-down strategy (one refactor commit
at a time tightens the bar), mirroring how CCN_MAX was driven to 10.

Wires the gate into:
  - Makefile.am: new lint-file-size target + EXTRA_DIST entry
  - .github/workflows/verify-build.yml: new step in the ubuntu lint
    lane, conditional on build-type == 'lint' (same gating as the
    sibling gates)

Architecture spec is not yet updated; the same gap exists for the
existing CCN/CPD gates (see specs/unworked_review_issues/
2026-05-21_121150_manual-validation.md) and is best closed in one
sweep.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: etr

.github/workflows/verify-build.yml

@@ -681,6 +681,10 @@ jobs:
       run: ./scripts/check-duplication.sh
       if: ${{ matrix.build-type == 'lint' && matrix.os-type == 'ubuntu' }}
 
+    - name: Run per-file line-count gate
+      run: ./scripts/check-file-size.sh
+      if: ${{ matrix.build-type == 'lint' && matrix.os-type == 'ubuntu' }}
+
     - name: Run libhttpserver configure
       run: |
         # Set memory check flags. They need to stay in step as env variables don't propagate across steps.

Makefile.am

@@ -43,6 +43,7 @@ EXTRA_DIST = libhttpserver.pc.in $(DX_CONFIG) scripts/extract-release-notes.sh s
 	scripts/check-doxygen.sh \
 	scripts/check-soversion.sh scripts/check-parallel-install.sh \
 	scripts/check-complexity.sh scripts/check-duplication.sh \
+	scripts/check-file-size.sh \
 	scripts/verify-installed-examples.sh \
 	test/headers/consumer_direct.cpp test/headers/consumer_detail.cpp test/headers/consumer_umbrella.cpp \
 	test/headers/consumer_post_umbrella.cpp \
@@ -366,7 +367,15 @@ lint-duplication:
 	@echo "=== lint-duplication: enforce zero copy/paste duplication ==="
 	@$(top_srcdir)/scripts/check-duplication.sh
 
-.PHONY: check-headers check-install-layout check-hygiene check-examples check-readme check-release-notes check-doxygen check-soversion check-parallel-install lint-complexity lint-duplication
+# Per-file line-count gate. Fails if any src/ .cpp/.hpp exceeds
+# FILE_LOC_MAX (default in the script; ratcheted down toward the
+# long-term 500-line target as each offender is decomposed). Not wired
+# into `make check` — invoked directly by CI's `lint` lane.
+lint-file-size:
+	@echo "=== lint-file-size: enforce per-file line-count ceiling ==="
+	@$(top_srcdir)/scripts/check-file-size.sh
+
+.PHONY: check-headers check-install-layout check-hygiene check-examples check-readme check-release-notes check-doxygen check-soversion check-parallel-install lint-complexity lint-duplication lint-file-size
 
 # TASK-039: top-level convenience rule that descends into test/ to
 # build and run the bench binaries (see test/Makefile.am and

scripts/check-file-size.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+#
+# check-file-size.sh — enforce a per-file line-count ceiling on the C++
+# library sources.
+#
+# Scope: src/ (library code only). test/ and examples/ are not scanned —
+# test fixtures and demo scaffolding legitimately grow large and are not
+# the subject of this gate.
+#
+# Scanned extensions: .cpp, .hpp (matches cpplint's --extensions=cpp,hpp
+# and the v2.0 source convention; no .h / .cc in src/).
+#
+# Metric: physical line count via `wc -l` (blank and comment lines
+# included). Physical lines were chosen over SLOC to avoid pulling in a
+# tokeniser dependency for this gate; the per-function complexity gate
+# already covers semantic density.
+#
+# Threshold knob:
+#   FILE_LOC_MAX  maximum physical lines per file (default below)
+#
+# FILE_LOC_MAX is currently set above the largest existing file so CI
+# stays green on the day this gate lands. The long-term target is 500
+# lines, matching the per-module ceiling used by the sibling project
+# under ../artistai (radon SLOC) and the natural break point where the
+# remaining files already comply.
+#
+# The bar will be ratcheted down per refactor commit as each offender
+# is decomposed — same pattern used to drive CCN_MAX to 10 in
+# scripts/check-complexity.sh. New files must come in well below the
+# long-term target; lifting FILE_LOC_MAX is not allowed.
+#
+# Current offenders above the long-term 500-line target (2026-05-21):
+#   src/webserver.cpp                          2673
+#   src/http_request.cpp                       1175
+#   src/httpserver/webserver.hpp                845
+#   src/http_utils.cpp                          730
+#   src/httpserver/detail/webserver_impl.hpp    674
+#   src/httpserver/http_request.hpp             656
+#   src/httpserver/http_utils.hpp               505
+#
+# Exit codes:
+#   0  no violations
+#   1  one or more files exceed FILE_LOC_MAX
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+FILE_LOC_MAX="${FILE_LOC_MAX:-2700}"
+
+cd "$REPO_ROOT"
+
+echo "check-file-size: scanning src/ with FILE_LOC_MAX=$FILE_LOC_MAX"
+
+violations=0
+# -print0/read -d '' keeps the loop safe against any future filename with
+# whitespace, even though src/ today is plain ASCII.
+while IFS= read -r -d '' file; do
+    lines=$(wc -l < "$file" | tr -d '[:space:]')
+    if [ "$lines" -gt "$FILE_LOC_MAX" ]; then
+        echo "  $file: $lines lines (max $FILE_LOC_MAX)" >&2
+        violations=$((violations + 1))
+    fi
+done < <(find src -type f \( -name '*.cpp' -o -name '*.hpp' \) -print0)
+
+if [ "$violations" -gt 0 ]; then
+    echo "check-file-size: FAIL — $violations file(s) exceed FILE_LOC_MAX=$FILE_LOC_MAX" >&2
+    echo "  threshold lives in scripts/check-file-size.sh (FILE_LOC_MAX default)" >&2
+    exit 1
+fi
+
+echo "check-file-size: PASS — no file exceeds $FILE_LOC_MAX lines"