ci: publish coverage artefacts and add badge

.gitea/workflows/push-validation.yml

@@ -14,6 +14,14 @@ jobs:
     defaults:
       run:
         shell: bash
+    env:
+      ARTEFACT_BUCKET_NAME: ${{ vars.ARTEFACT_BUCKET_NAME }}
+      ARTEFACT_BUCKET_ENDPONT: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
+      ARTEFACT_BUCKET_REGION: ${{ vars.ARTEFACT_BUCKET_REGION }}
+      AWS_ACCESS_KEY_ID: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET }}
+      AWS_DEFAULT_REGION: ${{ vars.ARTEFACT_BUCKET_REGION }}
+      AWS_EC2_METADATA_DISABLED: true
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -26,11 +34,89 @@ jobs:
           cache: true
           cache-dependency-path: go.sum
 
+      - name: Install AWS CLI v2
+        uses: ankurk91/install-aws-cli-action@v1
+
+      - name: Verify AWS CLI
+        run: aws --version
+
       - name: Run full unit test suite with coverage
+        id: coverage
         run: |
           set -euo pipefail
+
           go test -covermode=atomic -coverprofile=coverage.out ./...
-          go tool cover -func=coverage.out
+          go tool cover -html=coverage.out -o coverage.html
+
+          total="$(go tool cover -func=coverage.out | awk '/^total:/ {sub(/%/, "", $3); print $3}')"
+          printf '{\n  "total": "%s"\n}\n' "$total" > coverage-summary.json
+          printf 'total=%s\n' "$total" >> "$GITHUB_OUTPUT"
+
+      - name: Generate coverage badge
+        env:
+          COVERAGE_TOTAL: ${{ steps.coverage.outputs.total }}
+        run: |
+          set -euo pipefail
+
+          color="$(awk -v total="$COVERAGE_TOTAL" 'BEGIN {
+            if (total >= 80) print "brightgreen";
+            else if (total >= 70) print "green";
+            else if (total >= 60) print "yellowgreen";
+            else if (total >= 50) print "yellow";
+            else print "red";
+          }')"
+
+          cat > coverage-badge.svg <<EOF
+          <svg xmlns="http://www.w3.org/2000/svg" width="126" height="20" role="img" aria-label="coverage: ${COVERAGE_TOTAL}%">
+            <linearGradient id="smooth" x2="0" y2="100%">
+              <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+              <stop offset="1" stop-opacity=".1"/>
+            </linearGradient>
+            <clipPath id="round">
+              <rect width="126" height="20" rx="3" fill="#fff"/>
+            </clipPath>
+            <g clip-path="url(#round)">
+              <rect width="63" height="20" fill="#555"/>
+              <rect x="63" width="63" height="20" fill="${color}"/>
+              <rect width="126" height="20" fill="url(#smooth)"/>
+            </g>
+            <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
+              <text x="32.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
+              <text x="32.5" y="14">coverage</text>
+              <text x="93.5" y="15" fill="#010101" fill-opacity=".3">${COVERAGE_TOTAL}%</text>
+              <text x="93.5" y="14">${COVERAGE_TOTAL}%</text>
+            </g>
+          </svg>
+          EOF
+
+      - name: Upload branch coverage artefacts
+        id: upload
+        run: |
+          set -euo pipefail
+
+          aws configure set default.s3.addressing_style path
+
+          repo_name="${GITHUB_REPOSITORY##*/}"
+          prefix="${repo_name}/branch/${GITHUB_REF_NAME}"
+          report_url="${ARTEFACT_BUCKET_ENDPONT%/}/${ARTEFACT_BUCKET_NAME}/${prefix}/coverage.html"
+          badge_url="${ARTEFACT_BUCKET_ENDPONT%/}/${ARTEFACT_BUCKET_NAME}/${prefix}/coverage-badge.svg"
+
+          aws --endpoint-url "${ARTEFACT_BUCKET_ENDPONT}" s3 cp coverage.html "s3://${ARTEFACT_BUCKET_NAME}/${prefix}/coverage.html" --content-type text/html
+          aws --endpoint-url "${ARTEFACT_BUCKET_ENDPONT}" s3 cp coverage-badge.svg "s3://${ARTEFACT_BUCKET_NAME}/${prefix}/coverage-badge.svg" --content-type image/svg+xml
+          aws --endpoint-url "${ARTEFACT_BUCKET_ENDPONT}" s3 cp coverage-summary.json "s3://${ARTEFACT_BUCKET_NAME}/${prefix}/coverage-summary.json" --content-type application/json
+
+          printf 'report_url=%s\n' "$report_url" >> "$GITHUB_OUTPUT"
+          printf 'badge_url=%s\n' "$badge_url" >> "$GITHUB_OUTPUT"
+
+      - name: Add coverage summary
+        run: |
+          {
+            echo '## Coverage'
+            echo
+            echo '- Total: `${{ steps.coverage.outputs.total }}%`'
+            echo '- Report: ${{ steps.upload.outputs.report_url }}'
+            echo '- Badge: ${{ steps.upload.outputs.badge_url }}'
+          } >> "$GITHUB_STEP_SUMMARY"
 
       - name: Recommend next release tag on main pushes
         if: ${{ github.ref == 'refs/heads/main' }}

README.md

@@ -1,5 +1,10 @@
 # vociferate
 
+[![Main Validation](https://git.hrafn.xyz/aether/vociferate/actions/workflows/push-validation.yml?branch=main&event=push)](https://git.hrafn.xyz/aether/vociferate/actions/workflows/push-validation.yml)
+[![Prepare Release](https://git.hrafn.xyz/aether/vociferate/actions/workflows/prepare-release.yml?event=workflow_dispatch)](https://git.hrafn.xyz/aether/vociferate/actions/workflows/prepare-release.yml)
+[![Do Release](https://git.hrafn.xyz/aether/vociferate/actions/workflows/do-release.yml?event=push)](https://git.hrafn.xyz/aether/vociferate/actions/workflows/do-release.yml)
+[![Coverage](https://s3.hrafn.xyz/aether-workflow-report-artefacts/vociferate/branch/main/coverage-badge.svg)](https://s3.hrafn.xyz/aether-workflow-report-artefacts/vociferate/branch/main/coverage.html)
+
 `vociferate` is an `aether` release orchestration tool written in Go for repositories that
 want changelog-driven versioning, automated release preparation, and repeatable
 tag publication.

internal/vociferate/vociferate.go

@@ -1,3 +1,9 @@
+// Package vociferate provides changelog-driven release preparation utilities.
+//
+// It updates version metadata, promotes the Unreleased changelog section into a
+// dated version section, recommends the next semantic version tag from pending
+// changelog entries, and normalizes changelog links when repository metadata is
+// available.
 package vociferate
 
 import (
@@ -21,8 +27,15 @@ var unreleasedHeadingRe = regexp.MustCompile(`(?m)^## \[Unreleased\](?:\([^\n)]*
 var releaseHeadingRe = regexp.MustCompile(`(?m)^## \[(\d+\.\d+\.\d+)\](?:\([^\n)]*\))? - `)
 
 type Options struct {
+	// VersionFile is the path to the file that stores the current version,
+	// relative to the repository root. When empty, release-version is used.
 	VersionFile string
+	// VersionPattern is a regular expression with exactly one capture group for
+	// extracting the current version from VersionFile.
+	// When empty, a line-oriented default matcher is used.
 	VersionPattern string
+	// Changelog is the path to the changelog file, relative to the repository
+	// root. When empty, changelog.md is used.
 	Changelog string
 }
 
@@ -38,6 +51,14 @@ type resolvedOptions struct {
 	Changelog   string
 }
 
+// Prepare updates version state and promotes the Unreleased changelog notes
+// into a new release section.
+//
+// The version may be provided with or without a leading "v" and releaseDate
+// must use YYYY-MM-DD formatting. Prepare updates both the configured version
+// file and changelog, and enriches changelog headings with repository links
+// when repository metadata can be derived from CI environment variables or the
+// origin git remote.
 func Prepare(rootDir, version, releaseDate string, options Options) error {
 	normalizedVersion := strings.TrimPrefix(strings.TrimSpace(version), "v")
 	if normalizedVersion == "" {
@@ -65,6 +86,16 @@ func Prepare(rootDir, version, releaseDate string, options Options) error {
 	return nil
 }
 
+// RecommendedTag returns the next semantic release tag (for example, v1.2.3)
+// based on the current version and Unreleased changelog content.
+//
+// Bump rules are:
+//   - major: Unreleased contains a Breaking section or Removed entries
+//   - minor: Unreleased contains Added entries
+//   - patch: all other cases
+//
+// When no previous release is present in the changelog, the base version is
+// treated as 0.0.0.
 func RecommendedTag(rootDir string, options Options) (string, error) {
 	resolved, err := resolveOptions(options)
 	if err != nil {