ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  CMAKE_GENERATOR: Ninja

jobs:
  # A matrix rather than a single job: -Wconversion and -Wold-style-cast fire on
  # different constructs under GCC and Clang, and Release exercises optimiser
  # assumptions that Debug never reaches. Both compilers, both configurations.
  build-and-test:
    name: ${{ matrix.compiler }} / ${{ matrix.build_type }}
    runs-on: ubuntu-24.04
    strategy:
      fail-fast: false
      matrix:
        compiler: [gcc, clang]
        build_type: [Debug, Release]
        include:
          - compiler: gcc
            cc: gcc-14
            cxx: g++-14
          - compiler: clang
            cc: clang-18
            cxx: clang++-18
    steps:
      - uses: actions/checkout@v5

      - name: Install toolchain
        run: |
          sudo apt-get update
          sudo apt-get install -y ninja-build ${{ matrix.compiler == 'clang' && 'clang-18' || 'g++-14' }}

      - name: Configure
        env:
          CC: ${{ matrix.cc }}
          CXX: ${{ matrix.cxx }}
        run: cmake -S . -B build -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}

      - name: Build
        run: cmake --build build -j "$(nproc)"

      - name: Test
        run: ctest --test-dir build --output-on-failure -j "$(nproc)"

  sanitizers:
    name: ${{ matrix.preset }}
    runs-on: ubuntu-24.04
    strategy:
      fail-fast: false
      matrix:
        preset: [asan, tsan]
    steps:
      - uses: actions/checkout@v5
      - name: Install toolchain
        run: sudo apt-get update && sudo apt-get install -y ninja-build clang-18
      - name: Configure
        env:
          CC: clang-18
          CXX: clang++-18
        # -fno-sanitize-recover=all is set in the preset: a UBSan finding must
        # fail the build, not print a note and carry on.
        run: cmake --preset ${{ matrix.preset }}
      - name: Build
        run: cmake --build --preset ${{ matrix.preset }} -j "$(nproc)"
      - name: Test
        env:
          ASAN_OPTIONS: detect_leaks=1:strict_string_checks=1:detect_stack_use_after_return=1
          UBSAN_OPTIONS: print_stacktrace=1
        run: ctest --preset ${{ matrix.preset }}

  benchmarks:
    name: benchmarks build and run
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5
      - name: Install toolchain
        run: sudo apt-get update && sudo apt-get install -y ninja-build

      # An option nobody exercises stops working quietly. MOTIONKIT_BUILD_BENCHMARKS
      # spent its first months pointing add_subdirectory() at a directory that
      # was empty -- and therefore untracked, and therefore absent on a fresh
      # checkout -- so turning the option on failed at configure time.
      #
      # The numbers are not asserted on. A shared runner has no isolated cores
      # and no real-time scheduling, so a threshold here would be a flake
      # generator. This job proves the benchmark still builds and still runs to
      # completion; the figures in the README come from a known machine.
      - name: Configure with benchmarks on
        run: |
          cmake -S . -B build -DCMAKE_BUILD_TYPE=Release             -DMOTIONKIT_BUILD_BENCHMARKS=ON -DMOTIONKIT_BUILD_TESTS=OFF
      - name: Build
        run: cmake --build build -j "$(nproc)"
      - name: Run
        run: ./build/benchmarks/motionkit-bench

  static-analysis:
    name: clang-tidy + clang-format
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5
      - name: Install toolchain
        run: sudo apt-get update && sudo apt-get install -y ninja-build clang-18 clang-tidy-18 clang-format-18

      - name: Check formatting
        # Runs the same script a developer runs, so the two cannot drift.
        # The previous inline find/xargs searched a directory that was empty
        # -- and therefore untracked, and absent on a fresh checkout -- so it
        # failed even when every file was correctly formatted.
        run: bash scripts/format.sh --check
      - name: clang-tidy
        env:
          CC: clang-18
          CXX: clang++-18
        run: |
          cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
          # Only .cpp files under src/. A header has no entry in the compilation
          # database, so passing one to clang-tidy makes it fall back to a default
          # command and emit spurious diagnostics. Headers are still analysed
          # through the translation units that include them, via HeaderFilterRegex
          # in .clang-tidy. The fetched GoogleTest tree is excluded by construction.
          find src -name '*.cpp' \
            | xargs clang-tidy-18 -p build --warnings-as-errors='*'

  install-consumer:
    name: installed package is consumable
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5
      - name: Install toolchain
        run: sudo apt-get update && sudo apt-get install -y ninja-build

      # Exporting targets is easy to get subtly wrong in a way no unit test
      # catches: the library builds, and then find_package() fails for whoever
      # depends on it. This job installs the package and compiles a fresh
      # consumer against it, so that breakage shows up here instead of
      # downstream.
      - name: Build and install
        run: |
          cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
            -DMOTIONKIT_BUILD_TESTS=OFF \
            -DCMAKE_INSTALL_PREFIX="$PWD/staged"
          cmake --build build -j "$(nproc)"
          cmake --install build

      - name: Compile a downstream consumer against the installed package
        run: |
          mkdir -p /tmp/consumer
          cat > /tmp/consumer/CMakeLists.txt <<'EOT'
          cmake_minimum_required(VERSION 3.24)
          project(consumer LANGUAGES CXX)
          find_package(motionkit REQUIRED)
          add_executable(consumer main.cpp)
          target_link_libraries(consumer PRIVATE motionkit::core)
          EOT
          cat > /tmp/consumer/main.cpp <<'EOT'
          #include <array>
          #include <cmath>
          #include <cstddef>
          #include "motionkit/core/calibration.hpp"
          #include "motionkit/core/cartesian.hpp"
          #include "motionkit/core/collision.hpp"
          #include "motionkit/core/dynamics.hpp"
          #include "motionkit/core/frame_graph.hpp"
          #include "motionkit/core/kinematics.hpp"
          #include "motionkit/core/trajectory.hpp"
          int main() {
            using namespace motionkit;
            const SE3 pose(SO3::rotZ(1.0), Vec3{1.0, 2.0, 3.0});
            if (!(pose.inverse() * pose).isApprox(SE3{}, 1e-12, 1e-12)) {
              return 1;
            }
            FrameGraph frames;
            const auto base = frames.declareRoot("base");
            if (!base) {
              return 2;
            }
            const auto tcp = frames.declareFrame("tcp", base.value, pose);
            if (!tcp) {
              return 3;
            }
            const auto resolved = frames.lookup(base.value, tcp.value);
            if (!resolved || !resolved.value.isApprox(pose, 1e-12, 1e-12)) {
              return 4;
            }
            // Every public header has to be reachable from the installed tree,
            // not just the one the first consumer happened to use.
            const std::array<Scalar, 2> here{0.0, 0.0};
            const std::array<Scalar, 2> there{1.0, 0.25};
            const std::array<MotionLimits, 2> limits{MotionLimits{2.0, 8.0, 40.0},
                                                     MotionLimits{2.0, 8.0, 40.0}};
            const auto move = SynchronizedTrajectory::plan(here, there, limits);
            if (!move || move.value.duration() <= 0.0) {
              return 5;
            }
            std::array<MotionSample, 2> setpoints{};
            if (!move.value.sample(move.value.duration(), setpoints)) {
              return 6;
            }
            if (std::abs(setpoints[1].position - 0.25) > 1e-12) {
              return 7;
            }
            // The kinematics header, through the installed tree.
            const SerialChain arm = SerialChain::sixAxisExample();
            std::array<Scalar, 6> joints{0.3, -0.6, 1.0, 0.4, 0.7, -0.2};
            const auto reached = arm.forward(joints);
            if (!reached) {
              return 8;
            }
            joints[0] += 0.1;
            const auto solved = arm.inverse(reached.value, joints);
            if (!solved || solved.value.position_error > 1e-6) {
              return 9;
            }
            // A free function rather than a member, so it exercises a different
            // part of the exported symbol set.
            const auto permitted = maximumSafeSpeed(0.3, limits[0]);
            if (!permitted || permitted.value <= 0.0) {
              return 10;
            }
            const auto stop =
                StopProfile::plan(MotionState{0.0, permitted.value, 0.0}, limits[0]);
            if (!stop || std::abs(stop.value.stoppingDistance() - 0.3) > 1e-9) {
              return 11;
            }
            // The dynamics header. Holding the example arm against gravity must
            // take a non-zero torque somewhere -- an all-zero result would mean
            // the installed inertias were lost rather than exported.
            const DynamicChain loaded = DynamicChain::sixAxisExample();
            std::array<Scalar, 6> torque{};
            if (loaded.gravityTorque(joints, torque) != DynamicsError::None) {
              return 12;
            }
            Scalar effort = 0.0;
            for (const Scalar t : torque) {
              effort += std::abs(t);
            }
            if (!(effort > 1e-6)) {
              return 13;
            }
            // The calibration header. A tool offset is planted, the poses that
            // would have touched one point with it are generated, and the
            // offset must come back -- which exercises the exported solver
            // rather than merely proving the header parses.
            const Vec3 planted{0.031, -0.017, 0.184};
            const Vec3 touched{0.612, -0.204, 0.338};
            std::array<SE3, 4> touches{};
            const std::array<SO3, 4> turns{
                SO3::fromRPY(0.0, 0.0, 0.0), SO3::fromRPY(0.4, -0.3, 0.9),
                SO3::fromRPY(-0.7, 0.5, 0.2), SO3::fromRPY(0.2, 1.1, -0.6)};
            for (std::size_t i = 0; i < turns.size(); ++i) {
              touches[i] = SE3{turns[i], touched - (turns[i] * planted)};
            }
            const auto tip = calibrateToolPoint(touches);
            if (!tip || (tip.value.flange_t_tool - planted).norm() > 1e-9) {
              return 14;
            }
            // The cartesian header, which is the one that depends on both
            // halves of the library, so it fails if either export is wrong.
            const std::array<MotionLimits, 6> joint_limits{
                MotionLimits{2.0, 8.0, 60.0}, MotionLimits{2.0, 8.0, 60.0},
                MotionLimits{2.0, 8.0, 60.0}, MotionLimits{2.0, 8.0, 60.0},
                MotionLimits{2.0, 8.0, 60.0}, MotionLimits{2.0, 8.0, 60.0}};
            const SE3 line_from = arm.forward(joints).value;
            const SE3 line_to{line_from.rotation(),
                              line_from.translation() + Vec3{0.05, 0.0, 0.0}};
            const auto line = CartesianPlan::plan(arm, joints, line_to, joint_limits);
            if (!line || !(line.value.duration() > 0.0)) {
              return 15;
            }
            std::array<Scalar, 6> along{};
            if (!line.value.sample(line.value.duration(), along)) {
              return 16;
            }
            if (!arm.forward(along).value.isApprox(line_to, 1e-5, 1e-5)) {
              return 17;
            }
            // ReachProfile through the installed package. From a state that is
            // already moving away from the goal, so a profile that quietly
            // ignored the initial velocity would land somewhere else.
            const auto turning =
                ReachProfile::plan(MotionState{0.0, 1.5, 0.0}, -0.8, limits[0]);
            if (!turning || !turning.value.reversed()) {
              return 18;
            }
            if (std::abs(turning.value.sample(turning.value.duration()).position + 0.8) >
                1e-9) {
              return 19;
            }
            // A blended route, which is the one call that exercises the whole
            // library at once: kinematics, the profiles and the new geometry.
            const std::array<SE3, 3> route{
                SE3{line_from.rotation(), line_from.translation() + Vec3{-0.08, 0.0, 0.0}},
                SE3{line_from.rotation(),
                    line_from.translation() + Vec3{-0.08, 0.0, -0.08}},
                SE3{line_from.rotation(),
                    line_from.translation() + Vec3{-0.16, 0.0, -0.08}}};
            const auto weaving =
                CartesianPlan::planThrough(arm, joints, route, joint_limits);
            if (!weaving || !(weaving.value.report().corner_deviation > 0.0)) {
              return 20;
            }
            if (weaving.value.report().waypoints != 4) {
              return 21;
            }
            std::array<Scalar, 6> ended{};
            if (!weaving.value.sample(weaving.value.duration(), ended) ||
                !arm.forward(ended).value.isApprox(route.back(), 1e-5, 1e-5)) {
              return 22;
            }
            // The collision header. A parked arm must be clear of itself --
            // the check that fails first if the exported allowed-collision set
            // did not survive the install.
            const auto guard = CollisionModel::sixAxisExample();
            if (!guard) {
              return 23;
            }
            const std::array<Scalar, 6> parked{};
            const auto nearest = guard.value.clearance(parked, {});
            if (!nearest || !(nearest.value.to_self > 0.0)) {
              return 24;
            }
            const std::array<Capsule, 1> fence{
                Capsule{Vec3{0.30, 0.0, 0.0}, Vec3{0.30, 0.0, 1.2}, 0.05}};
            const auto against = guard.value.clearance(parked, fence);
            if (!against || against.value.to_obstacles >= kNothingNear) {
              return 25;
            }
            // Pacing by difficulty, through the installed package. The move is
            // the one measured in ADR-0016, so a plan that quietly ignored the
            // option would come back at the evenly-spread duration instead.
            CartesianOptions spread;
            spread.pace_by_difficulty = true;
            const auto uneven =
                CartesianPlan::plan(arm, joints, line_to, joint_limits, spread);
            if (!uneven || !(uneven.value.duration() < line.value.duration())) {
              return 26;
            }
            return 0;
          }
          EOT
          cmake -S /tmp/consumer -B /tmp/consumer/build \
                -DCMAKE_PREFIX_PATH="$PWD/staged" -DCMAKE_BUILD_TYPE=Release
          cmake --build /tmp/consumer/build
          /tmp/consumer/build/consumer

  # The API reference is a gate before it is a website. Doxygen runs with
  # WARN_AS_ERROR, so a public entity added without a doc comment fails here,
  # in the same pull request that added it -- see ADR-0009. Verified against
  # this runner's doxygen 1.9.8 and against 1.15.0 locally.
  docs:
    name: API reference builds clean
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v5
      - name: Install toolchain
        run: sudo apt-get update && sudo apt-get install -y ninja-build doxygen

      - name: Record the Doxygen version
        # The gate's exact warning set belongs to a Doxygen version. Printing it
        # means a failure after a runner-image bump can be told apart from a
        # failure caused by the commit under test.
        run: doxygen --version

      - name: Build the reference
        run: |
          cmake -S . -B build -DMOTIONKIT_BUILD_DOCS=ON -DMOTIONKIT_BUILD_TESTS=OFF
          cmake --build build --target docs

      - name: Upload for publication
        # Deliberately still v3, but not for the reason first written here.
        #
        # It is a composite action with no Node runtime of its own, so it does
        # not appear in the deprecation notice directly -- and it still carries
        # one, because the upload-artifact it calls internally is a Node 20
        # action. That is the single warning the last run reported, down from
        # ten. Clearing it means a newer major of this action, which is a
        # different pairing with deploy-pages from the one GitHub ships in its
        # own Pages starter workflow, and that trade has not been made yet.
        uses: actions/upload-pages-artifact@v3
        with:
          path: build/docs/html

  # Publication is opt-in, and off until the repository says otherwise.
  #
  # Deploying needs Pages set to the "GitHub Actions" source, and on a private
  # repository it needs a plan that allows Pages at all. Neither is knowable
  # from inside the workflow, so a job that simply ran would put a red cross on
  # main for a setting nobody had been asked about. Set the repository variable
  # PUBLISH_DOCS to "true" once Pages is configured, and this starts publishing.
  publish-docs:
    name: publish the reference
    needs: docs
    if: github.event_name == 'push' && github.ref == 'refs/heads/main' && vars.PUBLISH_DOCS == 'true'
    runs-on: ubuntu-24.04
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5