akanealw/Charon
1
0
Fork 0
Code Issues Pull Requests Actions 16 Packages Projects Releases Wiki Activity

chore: clean .gitignore cache

Browse Source
This commit is contained in:
GitHub Actions
2026-01-26 19:22:05 +00:00
parent e5f0fec5db
commit f64e3feef8
1448 changed files with 468101 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

317
docs/plans/patch_coverage_spec.md Normal file
View File

@@ -0,0 +1,317 @@
# Patch Coverage Remediation Plan (Codecov) — Backend
**Created:** 2026-01-09
> Note: This plan was moved from `docs/plans/current_spec.md` to keep the current plan focused on security remediation.
## Goal
Restore **Codecov patch coverage** to green by ensuring **100% of modified lines** are executed by tests.
- **Codecov patch coverage:** 92.93866%
- **Reported missing patch lines:** ~99
Hard constraints:
- Do **not** lower Codecov thresholds.
- Fix with **targeted tests** (only add micro “test hooks” if absolutely unavoidable).
## Scope (two workstreams; both in-scope)
### Workstream A (required): Patch coverage fixes for 10 backend files
This workstream fixes Codecov **patch coverage** by adding targeted tests (and only minimal seams if unavoidable) for the following backend files:
1. backend/internal/api/handlers/plugin_handler.go
2. backend/internal/api/handlers/encryption_handler.go
3. backend/internal/api/handlers/credential_handler.go
4. backend/internal/api/handlers/settings_handler.go
5. backend/internal/api/handlers/crowdsec_handler.go
6. backend/internal/api/handlers/proxy_host_handler.go
7. backend/internal/api/handlers/security_handler.go
8. backend/internal/caddy/config.go
9. backend/internal/caddy/client.go
10. backend/internal/api/handlers/testdb.go (special: ignored in `.codecov.yml` but may still show up)
### Workstream B (required): Prevention updates (instructions + agent files)
This workstream updates the following files to ensure future production-code changes include the patch-coverage triage + tests needed to keep Codecov patch coverage green:
- .github/instructions/testing.instructions.md
- .github/instructions/copilot-instructions.md
- .github/instructions/taming-copilot.instructions.md
- .github/agents/Backend_Dev.agent.md
- .github/agents/QA_Security.agent.md
- .github/agents/Supervisor.agent.md
- .github/agents/Frontend_Dev.agent.md (only if frontend changes are involved; otherwise leave untouched)
Non-goals:
- No unrelated refactors.
- No new integration tests requiring external services.
## Missing Files Table (copy from Codecov patch report)
Codecov “Patch” view is the source of truth. Paste the **exact missing/partial line ranges** into this table.
Note: Codecov “Patch” view is the source of truth. This table is only for tracking what you copied from Codecov and what test you’ll add.
| File | Missing patch line ranges (Codecov) | Partial patch line ranges (Codecov) | Primary test strategy |
|------|-------------------------------------|-------------------------------------|-----------------------|
| backend/internal/api/handlers/plugin_handler.go | (paste) | (paste) | Gin handler tests (httptest) to hit error + warn-but-200 branches |
| backend/internal/api/handlers/encryption_handler.go | (paste) | (paste) | Handler tests for rotate/validate error + success branches |
| backend/internal/api/handlers/credential_handler.go | (paste) | (paste) | Handler tests for parse/notfound/service-error branches |
| backend/internal/api/handlers/settings_handler.go | (paste) | (paste) | Handler tests for URL test/SSRF + “reachable=false” mapping |
| backend/internal/api/handlers/crowdsec_handler.go | (paste) | (paste) | Handler tests using httptest.Server to force non-200/non-JSON branches |
| backend/internal/api/handlers/proxy_host_handler.go | (paste) | (paste) | Handler tests for JSON type coercion and invalid payload validation |
| backend/internal/api/handlers/security_handler.go | (paste) | (paste) | Handler tests for effective-status branches + validation branches |
| backend/internal/caddy/config.go | (paste) | (paste) | Unit tests for helper branches + config generation edge cases |
| backend/internal/caddy/client.go | (paste) | (paste) | Unit tests for HTTP non-200 + endpoint/parse branches |
| backend/internal/api/handlers/testdb.go | (paste) | (paste) | Prefer moving helpers into *_test.go; else fix ignore/path mismatch |
## Why patch coverage missed (common patterns)
Patch coverage misses are usually caused by newly-changed lines being in branches that existing tests don’t naturally hit:
- Error-only branches (DB errors, JSON decode failures, upstream non-200)
- “Warn but succeed” flows (HTTP 200 with a warning field)
- JSON type coercion (e.g., `map[string]any` decoding numbers vs strings)
- Env-driven branches (missing `t.Setenv` in tests)
- Codecov ignore/path normalization mismatch (repo-relative path vs module path in coverprofile)
## Handling partial (yellow) patch lines
Partial patch lines (yellow) usually mean the line executed, but **not all branches associated with that line** did.
Common causes:
- Short-circuit boolean logic (e.g., `a && b`, `a || b`) where tests only exercise one side.
- Multi-branch conditionals (`if/else if/else`, `switch`) where only one case is hit.
- Error wrapping/logging paths that run only when an upstream returns an error.
Guidance:
- Treat yellow lines like “missing branch coverage”, not “missing statement coverage”.
- Write the smallest additional test that triggers the unhit branch (invalid input, not-found, service error, upstream non-200, etc.).
- Prefer deterministic seams: `httptest.Server` for upstream failures; fake services/mocks for DB/service errors; explicit `t.Setenv` for env-driven branches.
## How to locate exact missing lines in Codecov (triage)
1. Open the PR in GitHub.
2. Open the Codecov check details (“Details” / “View report”).
3. Switch to **Patch** (not Project).
4. Filter to the 10 scoped files.
5. For each file, copy the exact missing (red) and partial (yellow) line ranges.
6. Map each range to a minimal test that executes the branch.
Local assist (for understanding branches; Codecov still authoritative):
- Run VS Code task: **Test: Backend with Coverage**.
- View coverage HTML: `go tool cover -html=backend/coverage.txt`.
## Remediation Plan (tight, test-first)
1. Extract missing patch line ranges from Codecov and fill the table above.
2. For each missing range:
- Identify the branch (if/switch/early return) causing it.
- Add the shortest test that executes it.
3. Re-run VS Code task **Test: Backend with Coverage**.
4. Confirm Codecov patch view is green (100% patch coverage).
## Per-File Testing Strategy (scoped)
Only add tests that hit the lines Codecov marks missing.
### 1) backend/internal/api/handlers/plugin_handler.go
- Prioritize handler tests that cover:
- invalid `:id` parsing → 400
- not found → 404
- DB update failures → 500
- loader reload/load failures (often warn-but-200) → assert response body, not just status
### 2) backend/internal/api/handlers/encryption_handler.go
- Add/extend tests to cover:
- request bind/validation errors → 400
- service-layer failures → 500
- success path + any new audit/log branches
### 3) backend/internal/api/handlers/credential_handler.go
- Add/extend tests to cover:
- invalid ID parse → 400
- not found → 404
- create/update invalid provider / credential validation failures (where applicable)
- “test credentials” endpoint: service error mapping
### 4) backend/internal/api/handlers/settings_handler.go
- Add/extend tests to cover:
- invalid URL input → 400
- SSRF-blocked / unreachable cases that return 200 but set `reachable=false`
- network failures and how they’re represented in the response
### 5) backend/internal/api/handlers/crowdsec_handler.go
- Use `httptest.Server` to deterministically cover:
- upstream non-200 responses
- upstream non-JSON responses
- query param forwarding (capture server request URL)
### 6) backend/internal/api/handlers/proxy_host_handler.go
- Add/extend tests that submit JSON payloads exercising type coercion:
- wrong types (string vs number) → 400
- boundary values (negative ports, missing required fields)
- normalization branches (if Codecov points to them)
### 7) backend/internal/api/handlers/security_handler.go
- Add/extend tests to cover:
- effective-status branch selection (settings vs DB vs defaults)
- validation branches (IP/CIDR parsing, enum validation, etc.)
### 8) backend/internal/caddy/config.go
- Prefer helper-level unit tests (cheaper and more targeted) to cover:
- header normalization helpers
- CSP/security header composition
- CIDR parsing and bypass list validation
- skip/empty branches (e.g., “missing provider config → skip policy”)
### 9) backend/internal/caddy/client.go
- Add/extend tests for:
- endpoint validation failures
- HTTP non-200 response branches
- parse/marshal error branches (only if Codecov points to them)
### 10) backend/internal/api/handlers/testdb.go (special)
If Codecov patch view includes this file:
What’s happening:
- `.codecov.yml` currently ignores `backend/internal/api/handlers/testdb.go`, but Go coverprofiles can report paths as module-import paths (example from `backend/coverage.txt`): `github.com/Wikid82/charon/backend/internal/.../testdb.go`.
- If Codecov is matching against the coverprofile path form, the repo-relative ignore may not apply.
Make it actionable:
1. Confirm what path form the coverprofile is using:
- `grep -n "testdb.go" backend/coverage.txt`
1. If the result is a module/import-path form (example: `github.com/Wikid82/charon/backend/internal/api/handlers/testdb.go`), add one additional ignore entry to `.codecov.yml` so it matches what Codecov is actually seeing.
- Minimal, explicit (exact repo/module path): `"**/github.com/Wikid82/charon/backend/internal/api/handlers/testdb.go"`
- More resilient (still narrow): `"**/github.com/**/backend/internal/api/handlers/testdb.go"`
Note:
- Do not add `"**/backend/internal/api/handlers/testdb.go"` unless it’s missing; the repo-relative ignore is already present.
Why this is minimal:
- `.codecov.yml` already ignores the repo-relative path, but ignore matching can fail if Codecov consumes coverprofile paths that include the module/import prefix.
- Only add the extra ignore if the grep confirms the import-path form is present.
Preferred approach (in order):
1. Move test-only helpers into a `_test.go` file.
- Caution: this is only safe if **no other packages’ tests import those helpers**. Anything in `*_test.go` cannot be imported by other packages.
1. Otherwise, keep the helper in non-test code but rely on `.codecov.yml` ignores that match the coverprofile path form.
## Prevention: required instruction/agent updates (diff-style)
These are the minimal guardrails to prevent future patch-coverage regressions.
### A) .github/instructions/testing.instructions.md
```diff
@@
## 3. Coverage & Completion
* **Coverage Gate:** A task is not "Complete" until a coverage report is generated.
* **Threshold Compliance:** You must compare the final coverage percentage against the project's threshold (Default: 85% unless specified otherwise). If coverage drops, you must identify the "uncovered lines" and add targeted tests.
+* **Patch Coverage Gate (Codecov):** If production code is modified, Codecov **patch coverage must be 100%** for the modified lines. Do not relax thresholds; add targeted tests.
+* **Patch Triage Requirement:** Plans must include the exact missing/partial patch line ranges copied from Codecov’s **Patch** view.
```
### B) .github/instructions/taming-copilot.instructions.md
```diff
@@
## Surgical Code Modification
- **Focus on the Core Request**: Generate code that directly addresses the user's request, without adding extra features or handling edge cases that were not mentioned.
+ **Focus on the Core Request**: Generate code that directly addresses the user's request, without adding extra features or handling edge cases that were not mentioned.
+ **Spec Hygiene**: When asked to update a plan/spec file, do not append unrelated/archived plans; keep it strictly scoped to the current task.
```
### C) .github/instructions/copilot-instructions.md
```diff
@@
3. **Coverage Testing** (MANDATORY - Non-negotiable):
- - **MANDATORY**: Patch coverage must cover 100% of new/modified code. This prevents CodeCov Report failing CI.
+ - **MANDATORY**: Patch coverage must cover 100% of modified lines (Codecov Patch view must be green). If patch coverage fails, add targeted tests for the missing patch line ranges.
```
### D) .github/agents/Backend_Dev.agent.md
```diff
@@
3. **Verification (Definition of Done)**:
@@
- - **Coverage (MANDATORY)**: Run the coverage script explicitly. This is NOT run by pre-commit automatically.
+ - **Coverage (MANDATORY)**: Run the coverage task/script explicitly and confirm Codecov patch view is green for modified lines.
```
### E) .github/agents/Frontend_Dev.agent.md (only if frontend changes are involved)
```diff
@@
3. **Verification (Quality Gates)**:
@@
- **Gate 3: Coverage (MANDATORY)**:
@@
- **MANDATORY**: Patch coverage must cover 100% of new/modified code. This prevents CodeCov Report failing CI.
+ - If patch coverage fails, identify missing patch line ranges in Codecov Patch view and add targeted tests.
```
### F) .github/agents/QA_Security.agent.md
```diff
@@
- - When creating tests, if there are folders that don't require testing make sure to update `.codecov.yml` to exclude them from coverage reports or this throws off the difference between local and CI coverage.
+ - Prefer fixing patch coverage with tests. Only adjust `.codecov.yml` ignores when code is truly non-production (e.g., test-only helpers), and document why.
```
### G) .github/agents/Supervisor.agent.md
```diff
@@
- - **Plan Completeness**: Does the plan cover all edge cases? Are there any missing components or unclear requirements?
+ - **Plan Completeness**: Does the plan cover all edge cases? Are there any missing components or unclear requirements?
+ - **Patch Coverage Completeness**: If coverage is in scope, does the plan include Codecov Patch missing/partial line ranges and the exact tests needed to execute them?
```
## Validation Checklist (patch-coverage scope)
Required vs optional alignment:
- Required for this plan to be considered complete: Workstream A + Workstream B changes landed.
- This validation checklist is intentionally focused on Workstream A (patch coverage remediation). For additional repo-wide Definition of Done items, follow `.github/instructions/copilot-instructions.md`.
- Workstream B validation is “diff applied + reviewer confirmation” (it doesn’t impact Go patch coverage directly).
Run these tasks in order:
1. **Test: Backend with Coverage**
- Pass criteria: task succeeds; `backend/coverage.txt` generated; zero failing tests.
- Outcome criteria: Codecov patch status becomes green (100% patch coverage).
1. **Lint: Pre-commit (All Files)** (optional; general DoD)
- Pass criteria: all hooks pass.