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

153 lines
7.5 KiB
Markdown

# Publish current CI badges through the assets mount
Apply this task to one repository at a time. Read the repository's local agent
instructions, inspect its existing CI and coverage setup, preserve unrelated
work, and follow its commit policy. Do not push or publish outside CI unless the
user explicitly requests it.
## Goal
Make the default branch expose three small, current SVG badges:
```text
<asset-mount>/coverage/<owner>/<project>/<default-branch>/version.svg
<asset-mount>/coverage/<owner>/<project>/<default-branch>/test.svg
<asset-mount>/coverage/<owner>/<project>/<default-branch>/coverage.svg
<asset-origin>/coverage/<owner>/<project>/<default-branch>/version.svg
<asset-origin>/coverage/<owner>/<project>/<default-branch>/test.svg
<asset-origin>/coverage/<owner>/<project>/<default-branch>/coverage.svg
```
Discover the canonical owner, project name, default branch, asset mount, and
public asset origin from repository or CI configuration. Do not infer them only
from the local checkout directory. Keep the default-branch component stable;
these URLs describe the latest default-branch build, not an immutable commit.
Retain only the three badges as Jenkins artifacts. Do not publish or retain
commit-addressed coverage directories, HTML, JSON, LCOV, or other detailed
reports unless the repository already has a separate requirement for them.
## CI behavior
1. Use the project's established test and line-coverage tools. Pin tools that
CI installs itself, and keep tool configuration in the conventional tracked
project file.
2. Enforce an honest coverage floor supported by useful behavior tests. Do not
exclude ordinary production code or distort code or tests to increase the
percentage.
3. Produce a temporary machine-readable coverage summary, extract and validate
a numeric percentage from 0 through 100, render `coverage/coverage.svg`, and
remove the summary.
4. Read the version from authoritative package or build metadata and render
`coverage/version.svg`. Do not duplicate the version in CI configuration.
5. Write a build-specific marker only after the test stage succeeds. In an
always-run cleanup action, render `coverage/test.svg` as `passing` only when
that marker exists; otherwise render it as `failing`. Remove the marker
afterward so an old workspace cannot affect a later build.
6. If coverage did not complete, render a neutral `-%` badge during cleanup.
Cleanup must run for both successful and failed builds so published status
cannot silently remain stale.
7. Archive exactly the three nonempty SVG files with fingerprinting on every
branch. Publish them only from the default branch. A missing or unwritable
publication mount is a CI failure.
8. Keep rendering and filesystem publication in small tracked scripts rather
than large Jenkins shell blocks. Use the repository's existing scripting
language when suitable; otherwise use portable POSIX `sh`.
Update the Jenkins success and failure summaries to mention tests, coverage,
badge generation, and any other gates that the pipeline actually runs.
## Renderer contract
Render badges locally and deterministically. Do not call an external badge
service.
- The version renderer accepts only characters valid for the project's version
format, grows the value segment for long versions, and enforces a sensible
minimum width.
- The test renderer accepts only `passing` or `failing` and selects green or
red respectively.
- The coverage renderer accepts `-` or a number from 0 through 100, rounds
numeric values, and selects documented green, yellow, red, or neutral colors.
- Reject invalid input before creating or replacing output.
- Escape all text inserted into XML.
- Center labels and values horizontally with `text-anchor="middle"`. In a
20-pixel badge, center text vertically at `y="10"` with
`dominant-baseline="middle"` instead of treating `y` as a font baseline.
- When POSIX `awk` prints a conditional expression, parenthesize it, for example
`print (width < 45 ? 45 : width)`, so the expression also works with FreeBSD
awk.
## Publication contract
The publication script receives the publication root and an explicit
allow-listed set of badge names. It must:
- require an absolute publication root and validate all arguments before
changing published state;
- create only the required owner, project, and default-branch directories;
- publish only `coverage.svg`, `test.svg`, and `version.svg` below the resolved
default-branch directory;
- verify every selected source badge exists, is a regular nonempty file, and is
not a symlink;
- migrate an old default-branch symlink by unlinking the symlink itself without
deleting its target, and reject any other non-directory branch destination;
- make directories mode `0755` and badges mode `0644` so the web server can
traverse and read them even under a restrictive umask;
- copy each badge to a temporary file in its destination directory and rename
it atomically over the public file;
- clean temporary files on ordinary failures and signals;
- quote paths and remain portable to the Jenkins worker's operating system;
- never recursively synchronize, prune, or delete the shared asset mount.
Do not automatically remove old commit-addressed directories. That is a
separate destructive migration requiring explicit authorization and exact path
verification.
## Repository updates
Place the live badges immediately below the README title, substituting the
resolved values:
```markdown
![version](<asset-origin>/coverage/<owner>/<project>/<default-branch>/version.svg)
![tests](<asset-origin>/coverage/<owner>/<project>/<default-branch>/test.svg)
![test coverage](<asset-origin>/coverage/<owner>/<project>/<default-branch>/coverage.svg)
```
Do not link them to a report that CI does not retain. Document the local
coverage command, enforced floor, version source, temporary summary, archived
files, publication path, and public URLs. Remove tracked generated badge files
and obsolete status snapshots.
If this task also owns the web-server configuration, mount public assets
read-only, disable directory listing, serve SVG with a restrictive content
security policy, and revalidate or use a short cache lifetime for mutable badge
URLs. Otherwise record these as deployment requirements without expanding the
repository change into unrelated infrastructure work.
## Verification
Before committing:
1. Run the repository's formatting, build/check, test, lint, and supported
toolchain gates relevant to the change.
2. Run the exact CI coverage command and confirm the enforced floor.
3. Confirm the temporary summary yields a valid percentage, is removed, and
exactly three nonempty SVGs are selected for archival.
4. Exercise normal and long versions, passing and failing test states, green,
yellow, red, and neutral coverage, and invalid input rejection.
5. Parse every rendered file as XML and rasterize representative badges to
inspect text placement.
6. Test publication with `umask 077` against a temporary absolute root. Verify
modes, atomic replacement, idempotence, and old-symlink migration without
deleting the old target.
7. Verify rejection of missing badges, relative roots, unwritable
destinations, and regular-file branch destinations.
8. Validate Jenkins syntax as far as local tooling permits, inspect the final
diff, commit the change, and confirm the worktree is clean.
Report the measured coverage, enforced floor, checks run, commit ID, and any
checks unavailable locally. Do not claim the public badges are live until a
successful default-branch Jenkins build has published them.