ci: reuse the normal build for an advisory ABI/API check, published safely

.ci-local/abicheck-components.json

@@ -0,0 +1,32 @@
+[
+  {
+    "name": "libpvxs",
+    "artifact": "lib/${EPICS_HOST_ARCH}/libpvxs.so*",
+    "header": [
+      "include/pvxs/*.h",
+      "include/pvxs/versionNum.h"
+    ],
+    "header_exclude": [
+      "include/pvxs/iochooks.h"
+    ],
+    "include": [
+      "include",
+      "${EPICS_BASE}/include",
+      "${EPICS_BASE}/include/os/Linux",
+      "${EPICS_BASE}/include/compiler/gcc"
+    ]
+  },
+  {
+    "name": "libpvxsIoc",
+    "artifact": "lib/${EPICS_HOST_ARCH}/libpvxsIoc.so*",
+    "header": [
+      "include/pvxs/iochooks.h"
+    ],
+    "include": [
+      "include",
+      "${EPICS_BASE}/include",
+      "${EPICS_BASE}/include/os/Linux",
+      "${EPICS_BASE}/include/compiler/gcc"
+    ]
+  }
+]

.ci-local/abicheck.yml

@@ -0,0 +1,30 @@
+# Extraction context for the advisory abicheck shadow check.
+#
+# This describes how the PUBLIC HEADERS are parsed for ABI/API extraction.
+# It does not change how PVXS itself is built: the libraries analysed are
+# exactly the ones `cue.py build` produced, with PVXS's normal flags.
+compile:
+  options:
+    # PVXS's supported consumer language mode is C++11, and that is what its
+    # own build uses.  Parsing the public headers in C++11 or C++14 against
+    # the runner's libstdc++ 13 is not possible with the supported CastXML
+    # (0.7.0, Clang 20): libstdc++ 13's <bits/char_traits.h> fails with
+    # "statement not allowed in constexpr function" in both modes.  Measured
+    # on 2026-09-16; a conda-forge GCC 16 libstdc++ is worse (it needs C++20
+    # to parse its own <type_traits>).
+    #
+    # This is therefore a deliberate, disclosed deviation of the extraction
+    # context from the consumer language mode, not a silent one, and it is
+    # applied identically to libpvxs and libpvxsIoc so the two components and
+    # both sides of every comparison are interpreted the same way.  Remove it
+    # as soon as a toolchain that parses the headers in C++11 is available.
+    - -std=c++17
+    #
+    # Deliberately NOT set here: PVXS_API_BUILDING (a library-build-only
+    # macro) and PVXS_ENABLE_EXPERT_API (an opt-in expert surface).  The
+    # headers are parsed the way an ordinary consumer sees them.
+assurance:
+  # A comparison that could not complete must be reported as incomplete, not
+  # as a clean result.  The shadow gate stays advisory; this controls what
+  # the analysis is allowed to claim, not whether CI goes red.
+  require_complete: true

.github/actions/abicheck-capture/action.yml

@@ -0,0 +1,158 @@
+name: 'PVXS ABI capture'
+description: >-
+  Capture ABI/API evidence for libpvxs and libpvxsIoc from an installation
+  that a normal PVXS build has already produced. Performs no build, no
+  comparison and no reporting.
+
+  What is PVXS-specific lives here: where the EPICS dependency was prepared
+  and which host architecture it built for. Everything else -- selecting the
+  real shared object out of its SONAME alias chain, checking it is an ELF
+  ET_DYN, agreeing the target machine between components, expanding the owned
+  header sets and refusing a stale exclusion -- belongs to abicheck's own
+  baseline Action, which reads the component declaration in
+  .ci-local/abicheck-components.json.
+
+  Used by the selected matrix leg of ci-scripts-build.yml (the candidate
+  capture) and by abicheck-baseline.yml's one-time historical bootstrap, so
+  the two produce identical baseline-sets from one definition.
+
+inputs:
+  top:
+    description: >
+      Root of the built PVXS tree to capture from. Defaults to the workspace;
+      the historical bootstrap builds into its own directory and points this
+      at it.
+    required: false
+    default: ''
+  output-dir:
+    description: 'Directory to write the baseline-set into.'
+    required: true
+  project-ref:
+    description: >
+      The revision actually built and analysed, recorded in the manifest.
+      For a pull_request build this is the merge commit, not the PR head.
+    required: true
+  profile:
+    description: 'Build-profile identifier recorded in the manifest.'
+    required: true
+  baseline-generation:
+    description: 'Scanner-compatibility generation recorded in the manifest.'
+    required: false
+    default: '1'
+  build-config:
+    description: 'Path to the abicheck extraction config.'
+    required: false
+    default: '.ci-local/abicheck.yml'
+  component-spec:
+    description: 'Path to the PVXS component declaration.'
+    required: false
+    default: '.ci-local/abicheck-components.json'
+  abicheck-ref:
+    description: 'Immutable abicheck revision the capture runs from.'
+    required: true
+
+outputs:
+  baseline-path:
+    description: 'The baseline-set directory that was written.'
+    value: ${{ steps.capture.outputs.baseline-path }}
+  content-digest:
+    description: "Digest over the manifest's artifact list."
+    value: ${{ steps.capture.outputs.content-digest }}
+  resolved-libraries:
+    description: 'The concrete artifact/header/include set that was dumped.'
+    value: ${{ steps.capture.outputs.resolved-libraries }}
+  machine:
+    description: 'The ELF machine both components agreed on (e.g. EM_X86_64).'
+    value: ${{ steps.capture.outputs.machine }}
+
+runs:
+  using: 'composite'
+  steps:
+    # The only project-specific knowledge left: where cue.py put EPICS Base
+    # and which host arch it built for.  These are build-system facts, not
+    # ABI facts, so abicheck deliberately hard-codes neither.
+    - name: Resolve EPICS build context
+      id: epics
+      shell: bash
+      env:
+        TOP: ${{ inputs.top || github.workspace }}
+        SPEC_IN: ${{ inputs.component-spec }}
+        WORKSPACE: ${{ github.workspace }}
+        SPEC_OUT: ${{ runner.temp }}/abicheck-components.resolved.json
+      run: |
+        set -eu
+
+        # The declaration belongs to the CHECKOUT, not to the tree being
+        # captured.  The historical bootstrap points `top` at an old
+        # revision that predates this file entirely, so resolving a
+        # relative spec path after `cd "$TOP"` would read a file that is
+        # missing (or, worse, a stale declaration) from that revision.
+        case "$SPEC_IN" in
+          /*) spec_in=$SPEC_IN ;;
+          *)  spec_in=$WORKSPACE/$SPEC_IN ;;
+        esac
+        [ -f "$spec_in" ] || {
+          echo "::error::component declaration $spec_in does not exist"
+          exit 64
+        }
+
+        cd "$TOP"
+
+        # configure/RELEASE.local is where cue.py records the prepared
+        # dependency.  We read it; we never rewrite it.
+        if [ -z "${EPICS_BASE:-}" ] && [ -f configure/RELEASE.local ]; then
+          EPICS_BASE=$(sed -n -E 's/^[[:space:]]*EPICS_BASE[[:space:]]*=[[:space:]]*//p' \
+            configure/RELEASE.local | tail -n 1)
+        fi
+        [ -n "${EPICS_BASE:-}" ] || {
+          echo "::error::EPICS_BASE is not set and configure/RELEASE.local does not name it"
+          exit 64
+        }
+
+        EPICS_HOST_ARCH=${EPICS_HOST_ARCH:-}
+        if [ -z "$EPICS_HOST_ARCH" ] && [ -x "$EPICS_BASE/startup/EpicsHostArch" ]; then
+          EPICS_HOST_ARCH=$("$EPICS_BASE/startup/EpicsHostArch")
+        fi
+        case "$EPICS_HOST_ARCH" in
+          linux-*) ;;
+          *)
+            echo "::error::this capture is declared for a native Linux host arch, got '${EPICS_HOST_ARCH:-<unset>}'"
+            exit 64
+            ;;
+        esac
+
+        # Render the two build-system values into the declaration.  Exactly
+        # these two placeholders are substituted -- not envsubst, which is
+        # not guaranteed on every runner image and would also expand any
+        # other '$' the declaration might legitimately contain.
+        sed -e "s|\${EPICS_BASE}|$EPICS_BASE|g" \
+            -e "s|\${EPICS_HOST_ARCH}|$EPICS_HOST_ARCH|g" \
+            "$spec_in" > "$SPEC_OUT"
+        if grep -q '\${' "$SPEC_OUT"; then
+          echo "::error::unsubstituted placeholder left in $SPEC_OUT"
+          grep -n '\${' "$SPEC_OUT" >&2
+          exit 64
+        fi
+
+        echo "epics-base=$EPICS_BASE" >> "$GITHUB_OUTPUT"
+        echo "host-arch=$EPICS_HOST_ARCH" >> "$GITHUB_OUTPUT"
+        echo "spec=$SPEC_OUT" >> "$GITHUB_OUTPUT"
+        echo "resolved component declaration:"
+        cat "$SPEC_OUT"
+
+    - name: Capture ABI snapshots (libpvxs, libpvxsIoc)
+      id: capture
+      uses: abicheck/abicheck/actions/baseline@80cf72abb5856eb623a6056fb35d06a66ad26774
+      with:
+        library-spec: ${{ steps.epics.outputs.spec }}
+        library-root: ${{ inputs.top || github.workspace }}
+        output-dir: ${{ inputs.output-dir }}
+        project-ref: ${{ inputs.project-ref }}
+        profile: ${{ inputs.profile }}
+        depth: headers
+        build-config: ${{ inputs.build-config }}
+        baseline-generation: ${{ inputs.baseline-generation }}
+        generator-action-ref: ${{ inputs.abicheck-ref }}
+        # A libpvxs snapshot is ~124 MB of JSON at this depth (measured).
+        # The decoded content is identical either way.
+        snapshot-compression: zstd

.github/actions/abicheck-publish-baseline/action.yml

@@ -0,0 +1,101 @@
+name: 'PVXS ABI baseline publication'
+description: >-
+  Package a baseline-set and attach it to a release, after checking that
+  the set really describes the profile it is being published as.
+
+  Shared by abicheck-baseline.yml's automatic and bootstrap paths so the
+  eligibility rules exist once.
+
+inputs:
+  baseline-path:
+    description: 'Baseline-set directory (manifest.json plus snapshots).'
+    required: true
+  profile:
+    description: 'Profile this set is being published as.'
+    required: true
+  tag:
+    description: 'Release tag to attach the asset to.'
+    required: true
+  overwrite:
+    description: >
+      Replace an existing asset of the same name. A published baseline is
+      an immutable reference: replacing it silently changes the meaning of
+      every comparison already made against it.
+    required: false
+    default: 'false'
+  github-token:
+    description: 'Token with contents: write for the release upload.'
+    required: true
+
+runs:
+  using: 'composite'
+  steps:
+    # actions/stage-baseline packages whatever it is given and explicitly
+    # does not check the manifest's own profile against the name it is
+    # published under, so a mismatch would produce an asset that
+    # resolve-baseline later rejects as wrong_profile for every consumer.
+    # Check it here, before anything is uploaded.
+    - name: Check the set describes the profile it is published as
+      shell: bash
+      env:
+        BASELINE_PATH: ${{ inputs.baseline-path }}
+        EXPECTED_PROFILE: ${{ inputs.profile }}
+      run: |
+        set -euo pipefail
+        manifest="$BASELINE_PATH/manifest.json"
+        test -s "$manifest" || { echo "::error::no manifest.json in $BASELINE_PATH"; exit 1; }
+        actual=$(jq -r '.profile // empty' "$manifest")
+        if [ "$actual" != "$EXPECTED_PROFILE" ]; then
+          echo "::error::baseline-set records profile '$actual' but is being published as '$EXPECTED_PROFILE'"
+          exit 1
+        fi
+        libs=$(jq -r '[.artifacts[].library] | sort | join(",")' "$manifest")
+        if [ "$libs" != "libpvxs,libpvxsIoc" ]; then
+          echo "::error::baseline-set covers '$libs', expected both libpvxs and libpvxsIoc"
+          exit 1
+        fi
+
+    - name: Package the baseline-set
+      id: stage
+      uses: abicheck/abicheck/actions/stage-baseline@80cf72abb5856eb623a6056fb35d06a66ad26774
+      with:
+        baseline-path: ${{ inputs.baseline-path }}
+        asset-name-template: 'abicheck-baseline-{profile}.tar.zst'
+        profile: ${{ inputs.profile }}
+
+    - name: Attach to the release
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.github-token }}
+        TAG: ${{ inputs.tag }}
+        ASSET: ${{ steps.stage.outputs.archive-path }}
+        OVERWRITE: ${{ inputs.overwrite }}
+      run: |
+        set -euo pipefail
+        test -s "$ASSET"
+        name=$(basename "$ASSET")
+
+        if ! gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+          echo "::error::no release exists for tag $TAG; create the release before publishing its baseline"
+          exit 1
+        fi
+
+        existing=$(gh release view "$TAG" --repo "$GITHUB_REPOSITORY" \
+                     --json assets --jq "[.assets[].name] | index(\"$name\") // empty")
+        if [ -n "$existing" ]; then
+          if [ "$OVERWRITE" != "true" ]; then
+            # Re-running publication for a release that already has its
+            # baseline is a no-op, not a silent replacement.
+            echo "::notice::$name is already published for $TAG; leaving the existing immutable asset in place"
+            exit 0
+          fi
+          # gh refuses an asset name that already exists unless --clobber
+          # is given, so the explicit-overwrite path has to pass it.  It is
+          # deliberately confined to this branch: the default path above
+          # never replaces a published baseline.
+          echo "::warning::replacing the existing $name for $TAG at explicit request"
+          gh release upload "$TAG" "$ASSET" --repo "$GITHUB_REPOSITORY" --clobber
+          exit 0
+        fi
+
+        gh release upload "$TAG" "$ASSET" --repo "$GITHUB_REPOSITORY"