Add include/cppcheck linting and extend strict warnings to every build (#81)

Introduces two new whole-repo static analysis passes, applies the strict
first-party warning set to every build that compiles our own code (not
just host), fixes what those turned up, and hardens the release
workflows.

New lint tooling
- `script/check-includes.sh` + `check_includes.py`: an
include-what-you-use pass over `src/`, `include/`, `tests/`,
`host_examples/`, and `examples/`, built on clang-include-cleaner. Files
with guarded ESP branches are analyzed twice: a host pass, and an ESP
pass with `-DESP_PLATFORM` against stub headers materialized from
`script/esp_stubs.py`, so ESP-only code paths are checked without a
cross toolchain. A .cpp may still rely on its matching .h's includes.
Supports `--fix` for unused-include removal.
- `script/cppcheck.sh`: whole-program cppcheck (warning, style,
unusedFunction) over first-party sources. It sees every caller in a
single pass, so it can flag functions that are dead beyond the public
API surface.
- `clang-tidy.sh` now passes `--warnings-as-errors='*'` so findings fail
CI even if `.clang-tidy` ever loses its WarningsAsErrors line.
- Both new checks run as CI jobs and are required by the merge gate.
`cppcheck` is pinned to 2.21.0 and built from source (cached) because
the distro package lags several minor versions and reports differently
than the version developers run locally.

Warning flags
- Extracted the wrapper warning set into `opus_wrapper_warning_flags()`
and applied it to the ESP-IDF component build as well as host. ESP-only
code paths (`#ifdef ESP_PLATFORM` branches, Xtensa sources) previously
compiled under strict warnings nowhere, since the host build never sees
them.
- Added `-Wmissing-prototypes`/`-Wmissing-declarations` and
`-Wold-style-cast` to the set, and applied the same flags to test
sources and `host_examples`.
- `-Werror` stays gated behind `ENABLE_WERROR` (default off), so
consumers building these source-distributed files with an arbitrary
toolchain get warnings only. CI turns it on for the host sanitizer build
and for both PlatformIO example builds, which act as the pinned ESP
gate.

Fixes for the newly enabled warnings
- Replaced C-style casts with `static_cast` across `src/`, tests, and
the benchmark examples. The end-trim arithmetic now stays in 64-bit
rather than narrowing early: the value derives from an untrusted granule
position and can exceed `SIZE_MAX` on 32-bit targets.
- Wrapped `OPUS_SET_GAIN`/`OPUS_SET_BITRATE` call sites in diagnostic
pragmas -- the C-style cast is inside the vendored libopus macro and
can't be fixed at the call site.
- Made file-local helpers in `opus_to_wav` static, added its missing
`<cstdint>`, and zero-initialized `EncodeResult` so the early
error-return path returns defined fields.
- Annotated the public accessors whose only callers are downstream
consumers, which cppcheck's unusedFunction cannot see.

API
- `decode()` and `conceal_loss()` on both decoders are now
[[nodiscard]], with a `warn_unused_result` fallback below C++17. These
report errors only through their return code, so ignoring it silently
loses failures.
- `OggOpusDecoder'`s constructor is now explicit.
- `ogg_opus_decoder.h` uses `<cstddef>`/`<cstdint>` instead of the C
headers.

Release and CI workflows
- release-drafter authenticates through a GitHub App token instead of
`GITHUB_TOKEN` plus a deploy key; the workflow's default token is now
granted no permissions at all.
- `publish.yml`: added a timeout to every job and re-granted contents:
read to the Espressif job, whose job-level permissions block had
replaced the workflow default that checkout relies on.
- Fixed the PlatformIO cache key: the nested expression inside
hashFiles() was passed as a literal string, so the key never varied by
example and never matched a real file.
- Dependabot PRs now carry `dependencies`/`github-actions` labels, and
the release-drafter version-resolver labels are
`force-major`/`force-minor` to avoid colliding with ordinary triage
labels.

Author: kahrendt

.github/dependabot.yml

@@ -4,4 +4,7 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    labels:
+      - "dependencies"
+      - "github-actions"
     open-pull-requests-limit: 10

.github/release-drafter.yml

@@ -11,11 +11,11 @@ categories:
 version-resolver:
   major:
     labels:
-      - "major"
+      - "force-major"
       - "breaking-change"
   minor:
     labels:
-      - "minor"
+      - "force-minor"
       - "new-feature"
   patch:
     labels:

.github/workflows/ci.yml

@@ -65,6 +65,70 @@ jobs:
           CLANG_TIDY: clang-tidy-18
         run: ./script/clang-tidy.sh
 
+  include-check:
+    name: Include check
+    if: github.event.action != 'labeled'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          submodules: false
+
+      - name: Initialize library submodules
+        run: git submodule update --init --depth 1 lib/opus lib/micro-ogg-demuxer
+
+      - name: Install clang-include-cleaner
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y clang-tools-18
+
+      - name: Run include check
+        env:
+          CLANG_INCLUDE_CLEANER: clang-include-cleaner-18
+        run: ./script/check-includes.sh
+
+  cppcheck:
+    name: Cppcheck
+    if: github.event.action != 'labeled'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      # Pin cppcheck and build it from source: ubuntu-latest's apt package lags
+      # by several minor versions and produces different findings than the
+      # version developers run locally (Homebrew). Bump deliberately, in step
+      # with local installs. The build is cached, so only the first run per
+      # version pays the compile.
+      CPPCHECK_VERSION: "2.21.0"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          submodules: false
+
+      - name: Initialize library submodules
+        run: git submodule update --init --depth 1 lib/opus lib/micro-ogg-demuxer
+
+      - name: Cache pinned cppcheck
+        id: cache-cppcheck
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/cppcheck-install
+          key: cppcheck-${{ env.CPPCHECK_VERSION }}-${{ runner.os }}
+
+      - name: Build pinned cppcheck
+        if: steps.cache-cppcheck.outputs.cache-hit != 'true'
+        run: |
+          git clone --depth 1 --branch "$CPPCHECK_VERSION" https://github.com/danmar/cppcheck /tmp/cppcheck
+          cmake -S /tmp/cppcheck -B /tmp/cppcheck/build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX="$HOME/cppcheck-install"
+          cmake --build /tmp/cppcheck/build -j"$(nproc)"
+          cmake --install /tmp/cppcheck/build
+
+      - name: Add pinned cppcheck to PATH
+        run: echo "$HOME/cppcheck-install/bin" >> "$GITHUB_PATH"
+
+      - name: Run cppcheck
+        run: ./script/cppcheck.sh
+
   build:
     name: Build
     if: github.event.action != 'labeled'
@@ -133,7 +197,7 @@ jobs:
 
       - name: Configure CMake with sanitizers
         run: >
-          cmake -B build -DENABLE_SANITIZERS=ON
+          cmake -B build -DENABLE_SANITIZERS=ON -DENABLE_WERROR=ON
           -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
           -DOPUS_ALLOCATION_MODE=${{ matrix.alloc_mode }} tests
 
@@ -339,7 +403,7 @@ jobs:
           path: |
             ~/.platformio
             examples/${{ matrix.example }}/.pio
-          key: pio-${{ matrix.example }}-${{ hashFiles('examples/${{ matrix.example }}/platformio.ini') }}
+          key: pio-${{ matrix.example }}-${{ hashFiles(format('examples/{0}/platformio.ini', matrix.example)) }}
           restore-keys: |
             pio-${{ matrix.example }}-
 
@@ -358,6 +422,8 @@ jobs:
     needs:
       - pre-commit
       - lint
+      - include-check
+      - cppcheck
       - build
       - test
       - conformance

.github/workflows/publish.yml

@@ -13,6 +13,7 @@ jobs:
   verify-version:
     name: Verify version matches tag
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Check library.json and idf_component.yml against the release tag
@@ -31,6 +32,9 @@ jobs:
   ci-gate:
     name: CI gate
     runs-on: ubuntu-latest
+    timeout-minutes: 5
+    # Reads check-run conclusions via the API; no checkout, so contents is not
+    # needed, but checks:read is.
     permissions:
       checks: read
     steps:
@@ -57,8 +61,9 @@ jobs:
 
   publish-platformio:
     name: Publish to PlatformIO
-    needs: [verify-version, ci-gate]
     runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: [verify-version, ci-gate]
     environment: platformio
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -79,12 +84,14 @@ jobs:
 
   publish-espressif:
     name: Publish to Espressif
-    needs: [verify-version, ci-gate]
     runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: [verify-version, ci-gate]
     environment: espressif
     permissions:
-      contents: read
       id-token: write
+      # Job-level permissions replace the workflow default, so re-grant the read checkout needs.
+      contents: read
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:

.github/workflows/release-drafter.yml

@@ -5,24 +5,32 @@ on:
     branches:
       - main
 
-permissions:
-  contents: write
-  pull-requests: read
+# Release automation routes every repo operation (release-drafter, checkout, and the version-bump
+# push) through the GitHub App token generated below, so the default GITHUB_TOKEN is unused here.
+# Grant it no permissions at all. GitHub always mints the token; the empty set just strips its powers.
+permissions: {}
 
 jobs:
   release-drafter:
     name: Release Drafter
     environment: release-drafter
     runs-on: ubuntu-latest
     steps:
+      - name: Generate a token
+        id: generate-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ secrets.ESPHOME_GITHUB_APP_ID }}
+          private-key: ${{ secrets.ESPHOME_GITHUB_APP_PRIVATE_KEY }}
+
       - uses: release-drafter/release-drafter@34d80673e067bdc0c24568d3af899c216adcfaa9 # v7.7.0
         id: drafter
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
 
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          ssh-key: ${{ secrets.DEPLOY_KEY }}
+          token: ${{ steps.generate-token.outputs.token }}
 
       - name: Update version files
         run: |

.gitignore

@@ -8,6 +8,9 @@ build/
 .libs/
 .deps/
 
+# Local marker recording which internal conventions version is used for this project.
+.conventions-version
+
 # ESP-IDF specific
 sdkconfig
 sdkconfig.old

CMakeLists.txt

@@ -95,6 +95,26 @@ if(ESP_IDF_BUILD)
     # Apply ESP-IDF configuration
     opus_configure_esp_idf(${COMPONENT_LIB} ${COMPONENT_DIR} ${OPUS_STAGED_DIR})
 
+    # Strict warnings for our own wrapper sources on the ESP-IDF build too - this is the build that
+    # ships to hardware and the only place ESP-only code paths (#ifdef ESP_PLATFORM branches, Xtensa
+    # sources) ever compile, so local warnings are most useful here. Scoped per-source to src/ via the
+    # same helper as the host build; the bundled upstream Opus C (registered in the same component) is
+    # never put through them. -Werror is gated behind ENABLE_WERROR exactly as on host (default off, so
+    # a consumer building the component against an arbitrary future IDF toolchain gets warnings only);
+    # CI's pinned ESP build passes -DENABLE_WERROR=ON, the only place ESP-only wrapper warnings actually
+    # become errors (the host -Werror build never compiles these branches).
+    option(ENABLE_WERROR "Treat warnings as errors" OFF)
+    opus_wrapper_warning_flags(MICRO_OPUS_ESP_WRAPPER_WARNINGS)
+    if(ENABLE_WERROR)
+        list(APPEND MICRO_OPUS_ESP_WRAPPER_WARNINGS -Werror)
+        # These sources build at -O2, where GCC's -Wmaybe-uninitialized is false-positive-prone, so
+        # keep it non-fatal (a definite -Wuninitialized still errors), matching the host block and
+        # opus_set_optimization_flags. The ESP toolchain is always GCC, so no compiler guard is needed.
+        list(APPEND MICRO_OPUS_ESP_WRAPPER_WARNINGS -Wno-error=maybe-uninitialized)
+    endif()
+    set_source_files_properties(${OGG_OPUS_SOURCES} PROPERTIES
+        COMPILE_OPTIONS "${MICRO_OPUS_ESP_WRAPPER_WARNINGS}")
+
 # ==============================================================================
 # Host Build
 # ==============================================================================
@@ -148,10 +168,9 @@ else()
     # Strict warnings for our own wrapper sources only. The bundled upstream Opus C is not clean
     # under this set and is never edited here, so it keeps the relaxed flags from
     # opus_set_optimization_flags(); scoping these per-source confines them to src/. ENABLE_WERROR
-    # makes them fatal in CI. Mirrors the warning set used across the micro-* libraries.
-    set(MICRO_OPUS_WRAPPER_WARNINGS
-        -Wall -Wextra -Wpedantic -Wshadow -Wconversion -Wsign-conversion -Wdouble-promotion
-        -Wformat=2 -Wimplicit-fallthrough)
+    # makes them fatal in CI. Mirrors the warning set used across the micro-* libraries (shared with
+    # the ESP-IDF build via opus_wrapper_warning_flags()).
+    opus_wrapper_warning_flags(MICRO_OPUS_WRAPPER_WARNINGS)
     if(ENABLE_WERROR)
         list(APPEND MICRO_OPUS_WRAPPER_WARNINGS -Werror)
         # These sources build at -O2 (above), where GCC's -Wmaybe-uninitialized is

cmake/functions.cmake

@@ -27,6 +27,37 @@ function(opus_set_common_definitions TARGET)
     )
 endfunction()
 
+# ==============================================================================
+# opus_wrapper_warning_flags
+# ==============================================================================
+# Returns (in OUT_VAR, in the caller's scope) the strict warning set applied to
+# our own first-party C++ wrapper sources (src/*.cpp) on BOTH the host and the
+# ESP-IDF component build. The bundled upstream Opus C is never put through these
+# (it is not clean under them by design), so callers scope the result to the
+# wrapper sources via set_source_files_properties().
+#
+# -Werror is deliberately NOT included here: each caller (host and ESP) appends it
+# under the ENABLE_WERROR guard, which defaults off. These sources are
+# source-distributed and consumers compile them with arbitrary future toolchains,
+# so with the guard off they get warnings only; CI's pinned host and ESP builds
+# pass -DENABLE_WERROR=ON, which is where the warnings actually become errors.
+#
+# Arguments:
+#   OUT_VAR - Name of the variable to populate in the caller's scope
+# ==============================================================================
+function(opus_wrapper_warning_flags OUT_VAR)
+    set(${OUT_VAR}
+        -Wall -Wextra -Wpedantic -Wshadow -Wconversion -Wsign-conversion -Wdouble-promotion
+        -Wformat=2 -Wimplicit-fallthrough
+        # Any function not declared in a header must be static, so -Wunused-function can see it go
+        # dead. Clang and GCC spell the C++ variant differently.
+        $<$<CXX_COMPILER_ID:Clang,AppleClang>:-Wmissing-prototypes>
+        $<$<CXX_COMPILER_ID:GNU>:-Wmissing-declarations>
+        # Require static_cast/reinterpret_cast over C-style casts (the wrapper sources are all C++).
+        $<$<COMPILE_LANGUAGE:CXX>:-Wold-style-cast>
+        PARENT_SCOPE)
+endfunction()
+
 # ==============================================================================
 # opus_set_optimization_flags
 # ==============================================================================

examples/decode_benchmark/platformio.ini

@@ -2,6 +2,11 @@
 platform = https://github.com/pioarduino/platform-espressif32/releases/download/54.03.20/platform-espressif32.zip
 framework = espidf
 monitor_speed = 115200
+; CI builds this example as the pinned ESP-IDF gate for the micro-opus component's first-party
+; wrapper warnings: -DENABLE_WERROR=ON turns them into errors here, the only place the ESP-only code
+; paths ever compile (the host -Werror build never sees them). Remove this line if you copy the
+; example and build against a newer/unpinned toolchain, where a new warning could hard-fail the build.
+board_build.cmake_extra_args = -DENABLE_WERROR=ON
 
 [env:esp32-s3]
 board = esp32-s3-devkitm-1

examples/decode_benchmark/src/decode_benchmark.cpp

@@ -241,7 +241,7 @@ static void log_decode_result(const char* prefix, DecodeResult* result) {
 
 // FreeRTOS task function for concurrent decoding
 static void decode_task(void* params) {
-    TaskParams* task_params = (TaskParams*)params;
+    TaskParams* task_params = static_cast<TaskParams*>(params);
     const AudioConfig* config = task_params->audio_config;
 
     ESP_LOGI(TAG, "Task %d starting %s decode...", task_params->task_id, config->name);