From edbdea6965153c5199e0e17aeabbb0de3d689d07 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sun, 4 Oct 2026 01:48:23 +0200 Subject: [PATCH] ci: generate and publish coverage badges --- .gitignore | 1 + Jenkinsfile | 85 ++++++++- docs/advanced.md | 35 +++- scripts/ci-coverage-badges.sh | 270 +++++++++++++++++++++++++++++ scripts/publish-coverage-badges.sh | 110 ++++++++++++ 5 files changed, 494 insertions(+), 7 deletions(-) create mode 100755 scripts/ci-coverage-badges.sh create mode 100755 scripts/publish-coverage-badges.sh diff --git a/.gitignore b/.gitignore index d3c82b9..a4612e7 100644 --- a/.gitignore +++ b/.gitignore @@ -38,6 +38,7 @@ pip-log.txt pip-delete-this-directory.txt # Unit test / coverage reports +coverage/ htmlcov/ .tox/ .nox/ diff --git a/Jenkinsfile b/Jenkinsfile index a40f09c..e4eeba8 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -23,6 +23,10 @@ pipeline { stage('Checkout') { steps { checkout scm + sh ''' + rm -rf coverage + mkdir -p coverage + ''' } } stage('Check tools') { @@ -57,7 +61,11 @@ pipeline { .venv/bin/coverage erase .venv/bin/coverage run -m unittest discover -s tests -v .venv/bin/coverage report - .venv/bin/coverage xml + .venv/bin/coverage json -o coverage/coverage-summary.json + coverage_value=$(.venv/bin/python -c 'import json; value = json.load(open("coverage/coverage-summary.json", encoding="utf-8"))["totals"]["percent_covered"]; assert isinstance(value, (int, float)) and not isinstance(value, bool) and 0 <= value <= 100; print(value)') + scripts/ci-coverage-badges.sh coverage --value "$coverage_value" + rm -f coverage/coverage-summary.json + touch "coverage/.coverage-ready-${BUILD_NUMBER}" ''' } } @@ -67,14 +75,85 @@ pipeline { sh 'python3 -m unittest discover -s integration -v' } } + stage('Record test success') { + steps { + sh 'touch "coverage/.tests-passed-${BUILD_NUMBER}"' + } + } } post { success { - echo 'repo-fix audit, license policy, coverage, and tests passed.' + echo 'repo-fix audit, license policy, tests, and coverage passed; badge generation and archival run during cleanup.' } failure { - echo 'repo-fix CI failed; check the audit, policy, coverage, and test stages above.' + echo 'repo-fix CI failed; cleanup will generate and archive test, coverage, and version badges for this build.' + } + cleanup { + script { + sh ''' + if [ -f "coverage/.tests-passed-${BUILD_NUMBER}" ]; then + scripts/ci-coverage-badges.sh test --value passing + else + scripts/ci-coverage-badges.sh test --value failing + fi + + if [ ! -f "coverage/.coverage-ready-${BUILD_NUMBER}" ]; then + scripts/ci-coverage-badges.sh coverage --value - + fi + + version=$(python3 -c 'import fix_submodules; print(fix_submodules.__version__)') + scripts/ci-coverage-badges.sh version --value "$version" + + rm -f coverage/coverage-summary.json \ + "coverage/.tests-passed-${BUILD_NUMBER}" \ + "coverage/.coverage-ready-${BUILD_NUMBER}" + + for badge in version test coverage; do + path="coverage/${badge}.svg" + if [ -L "$path" ] || [ ! -f "$path" ] || [ ! -s "$path" ]; then + echo "invalid badge artifact: $path" >&2 + exit 1 + fi + done + set -- coverage/*.svg + if [ "$#" -ne 3 ]; then + echo "expected exactly three SVG badge artifacts, found $#" >&2 + exit 1 + fi + for path do + case "$path" in + coverage/version.svg|coverage/test.svg|coverage/coverage.svg) ;; + *) echo "unexpected SVG artifact: $path" >&2; exit 1 ;; + esac + done + ''' + + archiveArtifacts( + artifacts: 'coverage/version.svg,coverage/test.svg,coverage/coverage.svg', + fingerprint: true, + allowEmptyArchive: false + ) + + def branchName = env.BRANCH_NAME ?: env.GIT_BRANCH + if (!branchName?.trim()) { + error('Jenkins must supply BRANCH_NAME (multibranch) or GIT_BRANCH (Pipeline from SCM).') + } + if (branchName.startsWith('refs/remotes/origin/')) { + branchName = branchName.substring('refs/remotes/origin/'.length()) + } else if (branchName.startsWith('origin/')) { + branchName = branchName.substring('origin/'.length()) + } + if (branchName == 'main') { + sh ''' + scripts/publish-coverage-badges.sh \ + /mnt/assets/coverage Chado repo-fix main \ + version test coverage + ''' + } else { + echo "Skipping mutable badge publication for branch ${branchName}; default branch is main." + } + } } } } diff --git a/docs/advanced.md b/docs/advanced.md index b505e1f..3a88b8c 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -32,12 +32,16 @@ To run the same branch-coverage check as CI: ```bash python3 -m venv .venv .venv/bin/python -m pip install -r requirements-ci.txt +.venv/bin/coverage erase .venv/bin/coverage run -m unittest discover -s tests -v .venv/bin/coverage report ``` -Coverage must remain at or above 80%. The threshold is intentionally modest so -it catches meaningful regressions without encouraging low-value tests. +This exact command enforces the 80% line-coverage floor configured in +`pyproject.toml`. The threshold is intentionally modest so it catches +meaningful regressions without encouraging low-value tests. CI additionally +writes `coverage/coverage-summary.json` temporarily to obtain the overall +percentage for the coverage badge, then removes that summary. The opt-in integration test shallow-clones `Ravenous/ravenous_roll20.git` through the HTTPS proxy and exercises dry-run @@ -59,6 +63,10 @@ from Ravenous and requires Python 3.10 or newer, Git, and network access to PyPI, vulnerability data, and the Gitea HTTPS proxy. It creates isolated virtual environments; uv and Docker are not required. +The job must expose `BRANCH_NAME` (multibranch) or `GIT_BRANCH` (Pipeline from +SCM). Cleanup fails safely when neither is available instead of risking mutable +badge publication from an unidentified branch. + Before testing, CI runs two focused dependency gates: - `pip-audit` 2.10.1 fails on known vulnerabilities or dependency-collection @@ -91,5 +99,24 @@ build parameter for an offline unit-test-only run. If the HTTPS clone requires authentication, configure Git credentials on the agent; interactive prompts are disabled and clone failures fail the build. -The pipeline checks out and tests only. It does not publish artifacts, send -checks, push commits, or deploy files. +The authoritative project version is `fix_submodules.__version__`, exposed as +the dynamic project version in `pyproject.toml`. During cleanup, including after +a failed build, Jenkins generates and archives exactly these fingerprinted +artifacts: + +- `coverage/version.svg` +- `coverage/test.svg` +- `coverage/coverage.svg` + +Only a default-branch (`main`) build publishes those three files to +`/mnt/assets/coverage/Chado/repo-fix/main/`. They are served at: + +- `https://assets.dandaedre.com/coverage/Chado/repo-fix/main/version.svg` +- `https://assets.dandaedre.com/coverage/Chado/repo-fix/main/test.svg` +- `https://assets.dandaedre.com/coverage/Chado/repo-fix/main/coverage.svg` + +Configure the public server to mount the assets read-only, disable directory +listing, serve SVG with a restrictive content security policy, and revalidate +these mutable URLs or give them a short cache lifetime. Jenkins publication and +public serving are deployment concerns; the pipeline does not push commits or +send external checks. diff --git a/scripts/ci-coverage-badges.sh b/scripts/ci-coverage-badges.sh new file mode 100755 index 0000000..c76b094 --- /dev/null +++ b/scripts/ci-coverage-badges.sh @@ -0,0 +1,270 @@ +#!/bin/sh +set -eu + +usage() { + cat >&2 <<'EOF' +usage: $0 [options] + +Render one deterministic SVG badge. Defaults: + version --text version --value unknown --color #007ec6 + test --text tests --value passing --color #4c1 + coverage --text coverage --value - --color #9f9f9f --suffix % + +Options: + --text TEXT left-hand label + --value VALUE right-hand value + --color COLOR value background (#RGB or #RRGGBB) + --size PX font size, from 6 through 24 (default: 11) + --height PX badge height, from 14 through 64 (default: 20) + --label-width PX fixed label width instead of automatic sizing + --value-width PX fixed value width instead of automatic sizing + --suffix TEXT text appended to the displayed value + --output PATH output file (default: coverage/.svg) + -h, --help show this help + +Examples: + ./ci-coverage-badges.sh version --value 1.2.3 + ./ci-coverage-badges.sh test --value failing + ./ci-coverage-badges.sh coverage --value 87.4 + ./ci-coverage-badges.sh version --text release --value rc.12 --size 12 --color '#8a2be2' +EOF + exit "${1:-2}" +} + +[ "$#" -ge 1 ] || usage +kind=$1 +shift + +case "$kind" in + version) + text=version + value=unknown + color='#007ec6' + suffix= + output=coverage/version.svg + ;; + test) + text=tests + value=passing + color= + suffix= + output=coverage/test.svg + ;; + coverage) + text=coverage + value=- + color= + suffix=% + output=coverage/coverage.svg + ;; + -h|--help) usage 0 ;; + *) + echo "unsupported badge kind: $kind" >&2 + usage + ;; +esac + +font_size=11 +height=20 +label_width= +value_width= +color_set=false + +while [ "$#" -gt 0 ]; do + option=$1 + case "$option" in + --text|--value|--color|--size|--height|--label-width|--value-width|--suffix|--output) + [ "$#" -ge 2 ] || { + echo "missing value for $option" >&2 + exit 2 + } + option_value=$2 + shift 2 + case "$option" in + --text) text=$option_value ;; + --value) value=$option_value ;; + --color) color=$option_value; color_set=true ;; + --size) font_size=$option_value ;; + --height) height=$option_value ;; + --label-width) label_width=$option_value ;; + --value-width) value_width=$option_value ;; + --suffix) suffix=$option_value ;; + --output) output=$option_value ;; + esac + ;; + -h|--help) usage 0 ;; + *) + echo "unknown option: $option" >&2 + usage + ;; + esac +done + +validate_text() { + field_name=$1 + field_value=$2 + if ! printf '%sX\n' "$field_value" | LC_ALL=C awk ' + BEGIN { valid = 1 } + NR != 1 || $0 !~ /^[ -~]+X$/ || length($0) <= 1 { valid = 0 } + END { exit(valid == 0 ? 1 : 0) } + '; then + echo "$field_name must contain printable ASCII characters: $field_value" >&2 + exit 2 + fi +} + +validate_integer() { + field_name=$1 + field_value=$2 + minimum=$3 + maximum=$4 + case "$field_value" in + ''|*[!0-9]*) + echo "$field_name must be an integer from $minimum through $maximum: $field_value" >&2 + exit 2 + ;; + esac + if [ "$field_value" -lt "$minimum" ] || [ "$field_value" -gt "$maximum" ]; then + echo "$field_name must be an integer from $minimum through $maximum: $field_value" >&2 + exit 2 + fi +} + +validate_text text "$text" +validate_text value "$value" +if [ -n "$suffix" ]; then + validate_text suffix "$suffix" +fi +validate_integer size "$font_size" 6 24 +validate_integer height "$height" 14 64 +if [ -n "$label_width" ]; then + validate_integer label-width "$label_width" 20 1000 +fi +if [ -n "$value_width" ]; then + validate_integer value-width "$value_width" 20 1000 +fi +case "$output" in + ''|*/) echo "output must name an SVG file: $output" >&2; exit 2 ;; +esac + +case "$kind" in + test) + if [ "$color_set" = false ]; then + case "$value" in + passing) color='#4c1' ;; + failing) color='#e05d44' ;; + *) color='#9f9f9f' ;; + esac + fi + ;; + coverage) + if [ "$value" = '-' ]; then + [ "$color_set" = true ] || color='#9f9f9f' + else + if ! awk -v candidate="$value" 'BEGIN { + valid = candidate ~ /^[0-9]+([.][0-9]+)?$/ && candidate >= 0 && candidate <= 100 + exit(valid ? 0 : 1) + }'; then + echo "coverage value must be - or a number from 0 through 100: $value" >&2 + exit 2 + fi + value=$(awk -v candidate="$value" 'BEGIN { printf "%.0f", candidate }') + if [ "$color_set" = false ]; then + if [ "$value" -ge 90 ]; then + color='#4c1' + elif [ "$value" -ge 70 ]; then + color='#dfb317' + else + color='#e05d44' + fi + fi + fi + ;; +esac + +case "$color" in + \#[0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f]|\#[0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f][0-9A-Fa-f]) ;; + *) echo "color must be #RGB or #RRGGBB: $color" >&2; exit 2 ;; +esac + +display_value=$value$suffix +if [ -z "$label_width" ]; then + label_width=$(printf '%s\\n' "$text" | awk -v size="$font_size" '{ + width = int(length($0) * size * 0.64 + 14) + print (width < 35 ? 35 : width) + }') +fi +if [ -z "$value_width" ]; then + value_width=$(printf '%s\\n' "$display_value" | awk -v size="$font_size" '{ + width = int(length($0) * size * 0.64 + 14) + print (width < 35 ? 35 : width) + }') +fi + +badge_width=$((label_width + value_width)) +label_center=$(awk -v width="$label_width" 'BEGIN { printf "%.1f", width / 2 }') +value_center=$(awk -v left="$label_width" -v width="$value_width" 'BEGIN { + printf "%.1f", left + width / 2 +}') +vertical_center=$(awk -v badge_height="$height" 'BEGIN { printf "%.1f", badge_height / 2 }') + +xml_escape() { + sed \ + -e 's/&/\&/g' \ + -e 's//\>/g' \ + -e 's/"/\"/g' +} + +sed_replacement_escape() { + sed -e 's/[\\&|]/\\&/g' +} + +escaped_text=$(printf '%s' "$text" | xml_escape | sed_replacement_escape) +escaped_value=$(printf '%s' "$display_value" | xml_escape | sed_replacement_escape) +escaped_title=$(printf '%s: %s' "$text" "$display_value" | xml_escape | sed_replacement_escape) + +output_dir=${output%/*} +if [ "$output_dir" != "$output" ]; then + mkdir -p "$output_dir" +fi +temporary="${output}.tmp.$$" +trap 'rm -f "$temporary"' EXIT HUP INT TERM + +sed \ + -e "s/@BADGE_WIDTH@/$badge_width/g" \ + -e "s/@HEIGHT@/$height/g" \ + -e "s/@LABEL_WIDTH@/$label_width/g" \ + -e "s/@VALUE_WIDTH@/$value_width/g" \ + -e "s/@LABEL_CENTER@/$label_center/g" \ + -e "s/@VALUE_CENTER@/$value_center/g" \ + -e "s/@VERTICAL_CENTER@/$vertical_center/g" \ + -e "s/@FONT_SIZE@/$font_size/g" \ + -e "s/@COLOR@/$color/g" \ + -e "s|@TITLE@|$escaped_title|g" \ + -e "s|@TEXT@|$escaped_text|g" \ + -e "s|@VALUE@|$escaped_value|g" \ + >"$temporary" <<'EOF' + + @TITLE@ + + + + + + + + + + + + + + @TEXT@ + @VALUE@ + + +EOF + +mv "$temporary" "$output" +trap - EXIT HUP INT TERM diff --git a/scripts/publish-coverage-badges.sh b/scripts/publish-coverage-badges.sh new file mode 100755 index 0000000..2ef26c9 --- /dev/null +++ b/scripts/publish-coverage-badges.sh @@ -0,0 +1,110 @@ +#!/bin/sh +set -eu + +usage() { + echo "usage: $0 ROOT OWNER PROJECT DEFAULT_BRANCH NAME..." >&2 + exit 2 +} + +[ "$#" -ge 5 ] || usage +root=$1 +owner=$2 +project=$3 +default_branch=$4 +shift 4 + +case "$root" in + /*) ;; + *) echo "publication root must be absolute: $root" >&2; exit 2 ;; +esac +[ -d "$root" ] && [ -w "$root" ] || { + echo "publication root must be an existing writable directory: $root" >&2 + exit 2 +} + +validate_component() { + component_name=$1 + component_value=$2 + case "$component_value" in + ''|.|..|*[!A-Za-z0-9._-]*) + echo "$component_name is not a safe path component: $component_value" >&2 + exit 2 + ;; + esac +} + +validate_component owner "$owner" +validate_component project "$project" +validate_component default-branch "$default_branch" + +names= +for name do + case "$name" in + coverage|test|version) ;; + *) echo "unsupported badge name: $name" >&2; exit 2 ;; + esac + case " $names " in + *" $name "*) echo "duplicate badge name: $name" >&2; exit 2 ;; + esac + source_file="coverage/$name.svg" + [ ! -L "$source_file" ] && [ -f "$source_file" ] && [ -s "$source_file" ] || { + echo "badge source must be a regular, nonempty, non-symlink file: $source_file" >&2 + exit 2 + } + names="$names $name" +done + +ensure_directory() { + directory=$1 + if [ -L "$directory" ]; then + echo "publication path component must not be a symlink: $directory" >&2 + exit 2 + fi + if [ -e "$directory" ]; then + [ -d "$directory" ] || { + echo "publication path component is not a directory: $directory" >&2 + exit 2 + } + else + mkdir -m 0755 "$directory" + fi +} + +owner_directory="$root/$owner" +project_directory="$owner_directory/$project" +destination="$project_directory/$default_branch" +ensure_directory "$owner_directory" +ensure_directory "$project_directory" + +if [ -L "$destination" ]; then + unlink "$destination" +elif [ -e "$destination" ] && [ ! -d "$destination" ]; then + echo "default-branch destination is not a directory: $destination" >&2 + exit 2 +fi +ensure_directory "$destination" + +temporary_files= +cleanup() { + for temporary_file in $temporary_files; do + rm -f "$temporary_file" + done +} +trap cleanup 0 +trap 'exit 1' HUP INT TERM + +for name in $names; do + source_file="coverage/$name.svg" + target_file="$destination/$name.svg" + if [ -L "$target_file" ] || { [ -e "$target_file" ] && [ ! -f "$target_file" ]; }; then + echo "badge destination must be absent or a regular file: $target_file" >&2 + exit 2 + fi + temporary_file="$destination/.$name.svg.tmp.$$" + temporary_files="$temporary_files $temporary_file" + cp "$source_file" "$temporary_file" + chmod 0644 "$temporary_file" + mv -f "$temporary_file" "$target_file" +done + +trap - 0 HUP INT TERM