agent-tasks/tasks/ci-coverage-badges.task.md

193 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!-- Purpose: Generate and publish current version, test, and coverage badges through Jenkins. -->
<!-- Reference: This task uses one configurable POSIX sh renderer instead of three duplicated SVG renderers. -->
# Generate and publish current CI badges
Apply this task to one repository at a time. Read its local agent instructions, inspect its existing CI, package metadata, tests, coverage setup, README, Git remote, and default branch, and preserve unrelated work. Do not commit, push, start a Jenkins build, or publish outside CI unless the user explicitly requests it.
Use the generic renderer linked under **Renderer source** below. If the repository already has `render-version-badge.sh`, `render-test-badge.sh`, or `render-coverage-badge.sh`, retain them as small compatibility wrappers when callers or tests use those interfaces; do not keep three duplicated SVG templates.
## Required result
Generate exactly these mutable default-branch badges:
```text
coverage/version.svg
coverage/test.svg
coverage/coverage.svg
```
Set the Jenkins publication root to `/mnt/assets/coverage`. Publish to:
```text
/mnt/assets/coverage/<owner>/<project>/<default-branch>/version.svg
/mnt/assets/coverage/<owner>/<project>/<default-branch>/test.svg
/mnt/assets/coverage/<owner>/<project>/<default-branch>/coverage.svg
```
Serve them from:
```text
https://assets.dandaedre.com/coverage/<owner>/<project>/<default-branch>/version.svg
https://assets.dandaedre.com/coverage/<owner>/<project>/<default-branch>/test.svg
https://assets.dandaedre.com/coverage/<owner>/<project>/<default-branch>/coverage.svg
```
Resolve the owner, canonical project name, and default branch from repository and CI configuration. Do not infer them only from the checkout directory, and preserve deliberate spellings.
Add all three public image references immediately below the README title. Generated SVG files and temporary coverage reports must remain ignored and untracked.
## Generic renderer contract
Install the linked script as executable `scripts/ci-coverage-badges.sh`. It renders one badge per invocation and supplies useful defaults:
```sh
scripts/ci-coverage-badges.sh version --value 1.2.3
scripts/ci-coverage-badges.sh test --value passing
scripts/ci-coverage-badges.sh coverage --value 87.4
```
Without `--output`, those commands write the appropriate file below `coverage/`. Supported customizations include `--text`, `--value`, `--color`, `--size`, `--height`, `--label-width`, `--value-width`, `--suffix`, and `--output`.
The renderer must:
- validate its kind, options, printable text, numeric bounds, dimensions, and colors before replacing output;
- escape XML-sensitive text;
- calculate neat automatic widths with POSIX `awk`, using a minimum width;
- parenthesize conditional `awk` expressions for FreeBSD awk compatibility;
- center text with `text-anchor="middle"`, `dominant-baseline="middle"`, and half the badge height;
- round numeric coverage values and select red, yellow, green, or neutral colors;
- render test values as green for `passing`, red for `failing`, and neutral for custom values unless a color is explicit;
- create parent directories when needed;
- write a temporary file and atomically rename it over the output; and
- remove temporary files on ordinary failures and signals.
Semantic compatibility wrappers must continue to reject invalid legacy input. A version wrapper accepts the project version format, a test wrapper accepts only `passing` or `failing`, and a coverage wrapper accepts only `-` or a number from 0 through 100 through the generic renderer.
## Coverage and test lifecycle
Use the project’s established coverage tool. For Rust, keep its conventional tracked configuration, use locked dependency resolution, pin any CI-installed coverage tool, and enforce an honest documented line-coverage floor without excluding ordinary production code.
At the beginning of the build, remove and recreate the ignored `coverage/` output directory so a reused Jenkins workspace cannot provide stale markers or SVGs.
After every required test stage succeeds, create:
```text
coverage/.tests-passed-${BUILD_NUMBER}
```
Separate coverage measurement from the pass/fail decision. Always display the
actual measured line coverage and required floor in the CI console before
reporting success or failing the coverage stage, for example:
```text
Line coverage: 76.42%; required minimum: 80.00%
Coverage gate: FAIL (below required minimum)
```
Run coverage once and retain its exit status while processing its temporary
machine-readable summary. Ensure a below-threshold run still produces that
summary: if the tool cannot do so with its built-in threshold enabled, generate
the report first and enforce the same floor explicitly afterward. Do not let
shell fail-fast behavior or Jenkins' default `sh` failure handling abort before
printing diagnostics; capture the status explicitly and propagate failure after
reporting. Do not swallow errors with `|| true` or lose them through a logging
pipeline.
For a complete, valid report from the current build, extract and validate the
overall percentage, print it alongside the floor, render `coverage/coverage.svg`,
and create the following marker even if the measured coverage is below the floor:
```text
coverage/.coverage-ready-${BUILD_NUMBER}
```
The coverage-ready marker means a fresh, valid measurement and badge are ready;
it does not mean the coverage gate passed. Compare the unrounded measurement
against the floor, then print an explicit PASS or FAIL and fail the stage on a
threshold violation or any test, tool, parsing, or rendering error. Badge
rounding must not affect the gate. Retain the original tool failure diagnostics
and exit status in the console even if a report is available.
If coverage cannot be measured, print `Line coverage: unavailable`, the required
floor, and the concrete reason before failing. Never fabricate a percentage or
use a stale or partial report. Delete temporary summaries only after diagnostics
and badge processing; cleanup must also remove them on failure. Do not create
either marker before its own prerequisites are satisfied.
## Jenkins cleanup, archival, and publication
Finalize badges in `post { cleanup { ... } }`, which runs on both successful and failed builds:
1. Render `test.svg` as `passing` only if the current build’s test marker exists; otherwise render `failing`.
2. Preserve the measured coverage badge only if the current build’s coverage-ready marker exists; otherwise render neutral `-%`.
3. Read the version from authoritative package or workspace metadata and render `version.svg`; never duplicate the version in Jenkins configuration.
4. Remove temporary reports and both build-specific markers.
5. Require exactly the three expected SVGs to be regular, nonempty, non-symlink files.
6. Archive exactly those three SVGs with fingerprinting and `allowEmptyArchive: false`.
7. On the resolved default branch only, publish all three badges.
Publication must run from cleanup rather than only from the success handler.
On a failed default-branch build, publish the current test status according to
the test marker and preserve fresh measured coverage, including a value below
the floor. Publish neutral `-%` only when no valid current-build coverage badge
is ready. Never replace a valid measurement with neutral coverage merely
because the coverage gate or a later stage failed.
Branches other than the default branch generate and archive their badges but do not modify the public default-branch files. Confirm that the Jenkins job type actually supplies the branch variable used by the predicate.
## Publication script
Keep publication in a small tracked POSIX `sh` script. Its first argument is the already-complete root `/mnt/assets/coverage`; do not append another `coverage` component before the owner.
The script must:
- require an absolute, existing, writable publication root;
- accept only the allow-listed names `coverage`, `test`, and `version`, without duplicates;
- validate every `coverage/<name>.svg` source as a regular, nonempty, non-symlink file;
- resolve the destination as `<root>/<owner>/<project>/<default-branch>/`;
- reject symlink or non-directory owner and project components;
- migrate an old default-branch symlink by unlinking the symlink itself without deleting its target;
- create directories with mode `0755`;
- copy each source to a temporary file in the destination directory, set mode `0644`, and atomically rename it;
- clean unfinished temporary files on failure or signal;
- exit nonzero on validation, copying, permissions, or rename errors; and
- never recursively synchronize, prune, or delete the shared asset mount.
## README and documentation
Place the three live public badge references directly below the README title and require each resolved URL exactly once. Remove tracked generated badges and obsolete status snapshots.
Document the exact local coverage command, enforced floor, authoritative version source, temporary summary, three archived files, publication directory, and public URLs. Update Jenkins success and failure summaries to mention tests, coverage, and badge generation accurately. Both summaries must include the measured coverage and floor, or explicitly state why coverage is unavailable.
If server configuration is outside the repository, only record that public assets should be mounted read-only, directory listing disabled, SVG served with a restrictive content security policy, and mutable URLs revalidated or given a short cache lifetime.
## Verification
Before reporting repository implementation complete:
1. Run the repository’s formatting, check/build, test, lint, and documentation gates.
2. Run the exact coverage command and confirm the enforced floor. Exercise
above-floor, exactly-at-floor, below-floor, tool/test failure, and
missing/invalid report cases using fixtures or stubs where practical.
Verify that the measurement and floor (or an explicit unavailable reason)
appear before the stage's PASS/FAIL decision, errors still fail the job,
and a valid below-floor badge survives cleanup and is selected for
archival/publication. Confirm an unavailable measurement produces neutral
coverage and never reuses a previous build's value.
3. Exercise default and customized badge rendering, normal and long versions, passing and failing tests, all coverage color bands, neutral coverage, custom sizing, and XML-sensitive text.
4. Confirm invalid kinds, options, values, dimensions, and colors fail without replacing a valid output.
5. Parse every generated SVG as XML.
6. Test publication against a temporary absolute root under `umask 077`; verify modes, atomic replacement, idempotence, rejection cases, and safe old-symlink migration.
7. Confirm only the three SVG files are selected for archival.
8. Confirm each public README URL appears exactly once.
9. Inspect the final diff and report every unavailable check honestly.
Implementation is complete when the repository changes and local checks above pass. Real Jenkins publication and public URL retrieval are separate deployment checkpoints. If Jenkins, `/mnt/assets`, or the public server is unavailable, report that checkpoint as `not verified`; do not treat it as passed, invent results, or call the repository implementation a failure merely because production access is unavailable.
The final report must separately state README references, CI generation, Jenkins archival configuration, real default-branch publication, public URL retrieval, measured coverage, enforced floor, and checks actually run. Do not claim badges are live solely because repository files were changed.
## Renderer source
Use the maintained [`scripts/ci-coverage-badges.sh`](https://proxy.dandaedre.com/gitea/Dandaedre/agent-tasks/src/branch/main/scripts/ci-coverage-badges.sh) file. Copy the script into the target repository instead of copying a stale embedded snapshot from this task, retain its executable mode, and record the source revision used when reproducibility matters.