Charon/docs/plans/current_spec.md

Backend Coverage Alignment + Buffer Plan

Date: 2026-02-16 Owner: Planning Agent Status: Active (unit tests + coverage only)

1) Goal and Scope

Goal:

• Determine why local backend coverage and CI/Codecov differ.
• Add enough backend unit tests to create a reliable buffer above the 85% gate.

In scope:

• Backend unit tests only.
• Coverage measurement/parsing validation.
• CI-parity validation steps.

Out of scope:

• E2E/Playwright.
• Integration tests.
• Runtime/security feature changes unrelated to unit coverage.

2) Research Findings (Current Repo)

2.1 CI vs local execution path

• CI backend coverage path uses codecov-upload.yml → bash scripts/go-test-coverage.sh → uploads backend/coverage.txt with Codecov flag backend.
• Local recommended path (test-backend-coverage skill) runs the same script.

2.2 Metric-basis mismatch (explicit)

• scripts/go-test-coverage.sh computes the percentage from go tool cover -func, whose summary line is total: (statements) XX.X%.
• codecov.yml project status for backend is configured with only: lines.
• Therefore:
  • Local script output is statement coverage.
  • CI gate shown by Codecov is line coverage.
  • These are related but not identical metrics and can diverge by about ~0.5-1.5 points in practice.

2.3 Likely mismatch drivers in this repo

1. Coverage metric basis:

• Local script: statements.
• Codecov status: lines.

2. Exclusion filter differences:

• Script excludes only internal/trace and integration packages.
• Codecov ignore list also excludes extra backend paths/files (for example logger/metrics and Docker-only files).
• Different include/exclude sets can shift aggregate percentages.

3. Package-set differences in developer workflows:

• Some local checks use go test ./... -cover (package percentages) instead of the CI-equivalent script with filtering and upload behavior.

4. Cache/artifact variance:

• Go test cache and Codecov carryforward behavior can hide small swings between runs if not cleaned/verified.

3) EARS Requirements

• WHEN backend coverage is evaluated locally, THE SYSTEM SHALL report both statement coverage (from go tool cover) and CI-relevant line coverage context (Codecov config basis).
• WHEN coverage remediation is implemented, THE SYSTEM SHALL prioritize deterministic unit tests in existing test files before adding new complex harnesses.
• WHEN validation is performed, THE SYSTEM SHALL execute the same backend coverage script used by CI and verify output artifacts (backend/coverage.txt, backend/test-output.txt).
• IF local statement coverage is within 0-1 points of the threshold, THEN THE SYSTEM SHALL require additional backend unit tests to produce a safety buffer targeting >=86% CI backend line coverage.
• WHEN evaluating pass/fail semantics, THE SYSTEM SHALL distinguish the effective Codecov pass condition from the engineering buffer target: with target: 85% and threshold: 1% in codecov.yml, CI may pass below 85% lines depending on Codecov threshold/rounding logic.

4) Highest-Yield Backend Test Targets (+1% with minimal risk)

Priority 1 (low risk, deterministic, existing test suites):

1. backend/internal/util/permissions.go

• Boost tests around:
  • CheckPathPermissions error branches (permission denied, non-existent path, non-dir path).
  • MapSaveErrorCode and SQLite-path helpers edge mapping.
• Why high-yield: package currently low (~71% statements) and logic is pure/deterministic.

2. backend/internal/api/handlers/security_notifications.go

• Extend security_notifications_test.go for normalizeEmailRecipients branch matrix:
  • whitespace-only entries,
  • duplicate/mixed-case addresses,
  • invalid plus valid mixed payloads,
  • empty input handling.
• Why high-yield: currently very low function coverage (~17.6%) and no external runtime dependency.

Priority 2 (moderate risk, still unit-level):

3. backend/internal/api/handlers/system_permissions_handler.go

• Add focused tests around logAudit non-happy paths (missing actor, nil audit service, error/no-op branches).
• Why: currently low (~25%) and can be exercised with request context + mocks.

4. backend/internal/api/handlers/backup_handler.go

• Add restore-path negative tests in backup_handler_test.go using temp files and invalid backup payloads.
• Why: function Restore is partially covered (~27.6%); additional branch coverage is feasible without integration env.

Do not prioritize for this +1% buffer:

• CrowdSec deep workflows requiring process/network/file orchestration for marginal gain-per-effort.
• Docker-dependent paths already treated as CI-excluded in Codecov config.

5) Implementation Tasks

Phase A — Baseline and mismatch confirmation

1. Capture baseline using CI-equivalent script:

• bash scripts/go-test-coverage.sh

2. Record:

• Script summary line (total: (statements) ...).
• Computed local statement percentage.
• Existing backend Codecov line percentage from PR check.

3. Document delta (statement vs line) for this branch.

Phase B — Add targeted backend unit tests

1. Expand tests in:

• backend/internal/util/permissions_test.go
• backend/internal/api/handlers/security_notifications_test.go

2. If additional buffer needed, expand:

• backend/internal/api/handlers/system_permissions_handler_test.go
• backend/internal/api/handlers/backup_handler_test.go

3. Keep changes test-only; no production logic changes unless a test reveals a real bug.

Phase C — Validate against CI-equivalent flow

1. bash scripts/go-test-coverage.sh | tee backend/test-output.txt
2. go tool cover -func=backend/coverage.txt | tail -n 1 (record statement total).
3. Confirm no backend test failures in output (FAIL lines).
4. Push branch and verify Codecov backend status (lines) in PR checks.

6) Exact Validation Sequence (mirror CI as closely as possible)

Run from repository root:

1. Environment parity:

• export GOTOOLCHAIN=auto
• export CGO_ENABLED=1
• CI Go-version parity check (must match .github/workflows/codecov-upload.yml):

  CI_GO_VERSION=$(grep -E "^  GO_VERSION:" .github/workflows/codecov-upload.yml | sed -E "s/.*'([^']+)'.*/\1/")
  LOCAL_GO_VERSION=$(go version | awk '{print $3}' | sed 's/^go//')
  if [ "$LOCAL_GO_VERSION" != "$CI_GO_VERSION" ]; then
    echo "Go version mismatch: local=$LOCAL_GO_VERSION ci=$CI_GO_VERSION"
    exit 1
  fi
  

2. Clean stale local artifacts:

• rm -f backend/coverage.txt backend/test-output.txt

3. Execute CI-equivalent backend coverage command:

• bash scripts/go-test-coverage.sh 2>&1 | tee backend/test-output.txt

4. Verify script metric type and value:

• grep -n 'total:' backend/test-output.txt
• go tool cover -func=backend/coverage.txt | tail -n 1

5. Verify test pass state explicitly:

• if grep -qE '^FAIL[[:space:]]' backend/test-output.txt; then
    echo 'unexpected fails'
    exit 1
  fi
  

6. CI confirmation:

• Open PR and check Codecov backend status (lines) for final gate outcome.

7) Risks and Mitigations

Risk 1: Statement/line mismatch remains misunderstood.

• Mitigation: Always record both local statement summary and Codecov line status in remediation PR notes.

Risk 2: Added tests increase flakiness.

• Mitigation: prioritize deterministic pure/helper paths first (internal/util, parsing/normalization helpers).

Risk 3: Buffer too small for CI variance.

• Mitigation: target >=86.0 backend in CI line metric rather than barely crossing 85.0.

8) Acceptance Criteria

1. Investigation completeness:

• Plan documents likely mismatch causes: metric basis, exclusions, package-set differences, cache/artifact variance.

2. Metric clarity:

• Plan explicitly states: local script reads Go statement coverage; CI gate evaluates Codecov lines.

3. Test scope:

• Only backend unit tests are changed.
• No E2E/integration additions.

4. Coverage result:

• Backend Codecov project status passes with practical buffer target >=86.0% lines (engineering target).
• Effective Codecov pass condition is governed by target: 85% with threshold: 1%, so CI may pass below 85.0% lines depending on Codecov threshold/rounding behavior.

5. Validation parity:

• CI-equivalent script sequence executed and results captured (backend/coverage.txt, backend/test-output.txt).