From ecd2164d7303d276b2d14251da06e4871681eb1c Mon Sep 17 00:00:00 2001 From: neal Date: Wed, 18 Nov 2026 13:17:59 -0500 Subject: [PATCH 1/3] feat: support c, c++ and assembly as one cmake language Microcontroller firmware mixes a startup file in assembly, a HAL in C and application code in C or C++ inside one build target, so the three are one detected language, cpp, present when the root holds a CMakeLists.txt. Three detectors over one build file would give three adapter columns that could never differ, and CodeQL already counts C and C++ as the single language c-cpp. CMake over GNU Make because the checks need what only CMake reports: a compilation database for clang-tidy, a test registry for ctest, and, for the run and package adapters still to come, the File API's list of executables. Make would push all three onto a list each repository keeps by hand. clang-tidy and clang-format read the compilation database intersected with the repository's own C and C++ files. That drops assembly, which neither tool can parse, along with vendored trees and sources fetched or generated into build/. The root build/ is pruned from every search, since FetchContent clones dependency trees into it, and scripts/clean removes it by path. ctest reads only the top-level CTestTestfile.cmake, which CMake writes only when the root calls enable_testing(). A unit's own call leaves every add_test() below it skipped behind a passing "No tests were found", so the test adapter refuses a nested test file that has no top-level one. run and package stay absent, so scripts/run and scripts/package report unavailable for a C or C++ unit. A firmware unit's ship targets wait until one exists. ADR 0011 records the decision. Generated-By: claude-opus-5-5 --- .github/actions/setup-toolchains/action.yml | 16 ++ CLAUDE.md | 6 +- .../docs/github_repository_structure.md | 10 ++ .../actions/setup-toolchains/action.yml | 16 ++ .../src/base-repo/CLAUDE.md | 4 +- .../src/base-repo/scripts/clean | 6 +- .../src/base-repo/scripts/libs/dependabot.sh | 7 +- .../src/base-repo/scripts/libs/detect.sh | 166 +++++++++++++++--- .../src/base-repo/scripts/structure | 3 + .../base-repo/scripts/tests/capabilities-test | 100 +++++++++-- .../src/base-repo/scripts/tests/clean-test | 12 ++ .../scripts/tests/unit-commands-test | 2 +- apps/repo-builder/src/references/lifecycle.md | 3 +- ...-cpp-and-assembly-as-one-cmake-language.md | 108 ++++++++++++ docs/adrs/index.md | 1 + docs/language-ranking.md | 2 +- scripts/clean | 6 +- scripts/libs/dependabot.sh | 7 +- scripts/libs/detect.sh | 166 +++++++++++++++--- scripts/structure | 3 + scripts/tests/capabilities-test | 100 +++++++++-- scripts/tests/clean-test | 12 ++ scripts/tests/unit-commands-test | 2 +- 23 files changed, 677 insertions(+), 81 deletions(-) create mode 100644 docs/adrs/0011-support-c-cpp-and-assembly-as-one-cmake-language.md diff --git a/.github/actions/setup-toolchains/action.yml b/.github/actions/setup-toolchains/action.yml index 6e6f70b9..ee5b2a3b 100644 --- a/.github/actions/setup-toolchains/action.yml +++ b/.github/actions/setup-toolchains/action.yml @@ -91,3 +91,19 @@ runs: - name: Set up Gradle if: steps.detect.outputs.kotlin == 'true' uses: gradle/actions/setup-gradle@8da46b539cd8fe6ab27ca75128919a18d757604c # v6 + + # The hosted Ubuntu image ships CMake, GCC and Clang with clang-format and + # clang-tidy, so nothing installs here. Their versions are printed instead: + # clang-format's layout changes between releases, and a format check that + # passes locally and fails here is that difference before it is the code. + - name: Report C and C++ toolchain + if: steps.detect.outputs.cpp == 'true' + shell: bash + run: | + for tool in cmake cc c++ clang-format clang-tidy; do + if ! command -v "$tool" > /dev/null 2>&1; then + echo "::error::$tool is not on this runner. A GitHub-hosted Ubuntu image ships it; a self-hosted host must install it before a C or C++ repository can build here." + exit 1 + fi + "$tool" --version | head -n 1 + done diff --git a/CLAUDE.md b/CLAUDE.md index accd712c..bed4a468 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -86,7 +86,7 @@ Where a new file goes. `scripts/structure` enforces every placement rule here as - `tmp/` — gitignored scratch space - a toolchain folder, such as `gradle/` beside `gradlew`; see below -Root *files* are permitted by name: the eight the template ships, `.repo-template.json`, `.gitmodules`, `.structure-allow`, `GLOSSARY.md`, `GLOSSARY-MAP.md`, every addition by occasion, and the root workspace manifests and lockfiles of five of the six languages (Swift has none; see the orphan-manifest rule). `.gitkeep` is permitted anywhere. Anything else needs an entry in `.structure-allow`. +Root *files* are permitted by name: the eight the template ships, `.repo-template.json`, `.gitmodules`, `.structure-allow`, `GLOSSARY.md`, `GLOSSARY-MAP.md`, every addition by occasion, the root workspace manifests and lockfiles of six of the seven languages (Swift has none; see the orphan-manifest rule), and C and C++'s `.clang-format` and `.clang-tidy`, which read no manifest. `.gitkeep` is permitted anywhere. Anything else needs an entry in `.structure-allow`. **`apps/` holds the smallest deployable units**, possibly just one. @@ -109,7 +109,7 @@ The two facts vary independently and every pairing is legal: a scheduled job run Reading the file needs `jq`, which `scripts/doctor` requires. Without it the audit reports `unavailable` and fails, and the suites that exercise a unit skip every case. -**`tests/integration/` is the integration tier**, at any scope holder. It needs no placement rule, since `tests/` may nest its own kind; the name matters only to the capabilities: `scripts/integration` runs it and the gate does not. pytest and `go test ./...` discover by walking the tree, so their exclusion is wired; the other four languages declare their test set (an npm script, a Gradle source set, a SwiftPM or Cargo test target), and that declaration leaves the tier out. +**`tests/integration/` is the integration tier**, at any scope holder. It needs no placement rule, since `tests/` may nest its own kind; the name matters only to the capabilities: `scripts/integration` runs it and the gate does not. pytest and `go test ./...` discover by walking the tree, so their exclusion is wired; the other five declare their test set (an npm script, a Gradle source set, a SwiftPM or Cargo test target, a CMake `add_test()`), and that declaration leaves the tier out. **Scoped folders nest freely but never hold a `src/`.** `libs/`, `tests/`, `scripts/`, `tools/`, `assets/`, `config/`, `docs/`, and `deploy/` may nest another kind (`scripts/tests/libs/`) or their own (`tests/` under `tests/`). Choose the folder whose scope matches the file's. @@ -129,7 +129,7 @@ Reading the file needs `jq`, which `scripts/doctor` requires. Without it the aud Three rules are about content, and no script can settle them: whether `libs/` holds what several apps share, whether `tests/` spans them, and whether a file sits at its own scope. `scripts/structure` reports them `not-applicable` rather than guessing from paths. -A package whose language has no root manifest fails the run, because that manifest is what lists it: `go list -m` names only `go.work`'s `use` entries, and the Gradle settings file likewise. Swift is excluded: it has no root manifest, and nested packages are how a Swift repository is meant to look. The failure names the root manifest to add. +A package whose language has no root manifest fails the run, because that manifest is what lists it: `go list -m` names only `go.work`'s `use` entries, the Gradle settings file likewise, and CMake configures only what the root `CMakeLists.txt` reaches through `add_subdirectory()`. Swift is excluded: it has no root manifest, and nested packages are how a Swift repository is meant to look. The failure names the root manifest to add. ## Repository settings diff --git a/apps/github-repository-template/docs/github_repository_structure.md b/apps/github-repository-template/docs/github_repository_structure.md index 744770ea..c5e9bac5 100644 --- a/apps/github-repository-template/docs/github_repository_structure.md +++ b/apps/github-repository-template/docs/github_repository_structure.md @@ -262,3 +262,13 @@ These languages have built-in or universally accepted package managers, meaning **App-level:** `build.gradle.kts` Unlike the package managers above, Gradle writes no lockfile by default. Dependency locking is opt-in and produces `gradle.lockfile` per project only after it is enabled and written. Without it, builds are not reproducible across time. + +#### C, C++ and assembly + +One language, `cpp`, built by CMake: a single build file compiles all three. + +**Root-level:** `CMakeLists.txt` with `project()` and `enable_testing()`, reaching each unit through `add_subdirectory()`. CMake has no workspace file, so this file is the workspace. `.clang-format` and `.clang-tidy` sit beside it: neither tool reads a manifest, and each finds its file by walking up from the source. The binary directory is the gitignored root `build/`. + +**App-level:** `CMakeLists.txt` + +CMake writes no lockfile and Dependabot has no CMake ecosystem, so a `FetchContent` pin is one nothing bumps. clang-tidy and clang-format skip assembly, which neither can parse; CodeQL scans C and C++ without a build. A firmware unit's ship targets are not yet in the target vocabulary. diff --git a/apps/github-repository-template/src/base-repo/.github/actions/setup-toolchains/action.yml b/apps/github-repository-template/src/base-repo/.github/actions/setup-toolchains/action.yml index 6e6f70b9..ee5b2a3b 100644 --- a/apps/github-repository-template/src/base-repo/.github/actions/setup-toolchains/action.yml +++ b/apps/github-repository-template/src/base-repo/.github/actions/setup-toolchains/action.yml @@ -91,3 +91,19 @@ runs: - name: Set up Gradle if: steps.detect.outputs.kotlin == 'true' uses: gradle/actions/setup-gradle@8da46b539cd8fe6ab27ca75128919a18d757604c # v6 + + # The hosted Ubuntu image ships CMake, GCC and Clang with clang-format and + # clang-tidy, so nothing installs here. Their versions are printed instead: + # clang-format's layout changes between releases, and a format check that + # passes locally and fails here is that difference before it is the code. + - name: Report C and C++ toolchain + if: steps.detect.outputs.cpp == 'true' + shell: bash + run: | + for tool in cmake cc c++ clang-format clang-tidy; do + if ! command -v "$tool" > /dev/null 2>&1; then + echo "::error::$tool is not on this runner. A GitHub-hosted Ubuntu image ships it; a self-hosted host must install it before a C or C++ repository can build here." + exit 1 + fi + "$tool" --version | head -n 1 + done diff --git a/apps/github-repository-template/src/base-repo/CLAUDE.md b/apps/github-repository-template/src/base-repo/CLAUDE.md index 14590d9a..c6e9a55c 100644 --- a/apps/github-repository-template/src/base-repo/CLAUDE.md +++ b/apps/github-repository-template/src/base-repo/CLAUDE.md @@ -18,7 +18,7 @@ Use these instead of per-language tools. `check` and `fix` run for every languag `scripts/check` fails on any of these; pre-commit runs `scripts/structure` over the placement rules on every commit. - Root holds only `apps/`, `docs/`, `libs/`, `scripts/`, `tests/`, `tools/`, `deploy/`, `assets/`, `config/`, `examples/`, `vendor/`, `tmp/`, the toolchain folders below, and the dot-folders `.claude/`, `.github/`, `.devcontainer/`. -- Root files are permitted by name: the shipped dotfiles, `CLAUDE.md`, `GLOSSARY.md`, `GLOSSARY-MAP.md`, `.gitmodules`, `.structure-allow`, `.repo-template.json`, adopted addons, and each language's root manifests and lockfiles. Any other root file or folder needs an entry in `.structure-allow`. +- Root files are permitted by name: the shipped dotfiles, `CLAUDE.md`, `GLOSSARY.md`, `GLOSSARY-MAP.md`, `.gitmodules`, `.structure-allow`, `.repo-template.json`, adopted addons, each language's root manifests and lockfiles, and `.clang-format` and `.clang-tidy`. Any other root file or folder needs an entry in `.structure-allow`. - `apps//` is one unit: the smallest piece delivered on its own. Its code goes in `apps//src/`. Nothing sits directly in `apps/`. - Split a unit into domains only for distinct business areas: `apps///src/`. A unit has `src/` or domains, never both. Domains do not nest. - A root, unit, or domain may hold its own `libs/`, `tests/`, `scripts/`, `tools/`, `assets/`, `config/`, `docs/`, `deploy/`, `examples/`, or `vendor/`, scoped to it. Outside `examples/` and `vendor/`, these never contain `src/`. @@ -29,7 +29,7 @@ Use these instead of per-language tools. `check` and `fix` run for every languag - `docs/` takes Markdown; anything else there needs `.structure-allow`. - Below a `src/`, an `examples/`, a `vendor/`, or a toolchain folder, that tree's own language or tool decides the layout. - A path ending in `/` in `.structure-allow` exempts that whole prefix, for a tracked fixture tree. -- A package whose language has no root manifest fails the gate; add the root workspace manifest (`go.work`, `settings.gradle.kts`, and so on) that lists it. Swift is excepted: it has no root manifest. +- A package whose language has no root manifest fails the gate; add the root workspace manifest (`go.work`, `settings.gradle.kts`, a `CMakeLists.txt` that reaches it through `add_subdirectory()`, and so on) that lists it. Swift is excepted: it has no root manifest. These are conventions `scripts/structure` does not check: diff --git a/apps/github-repository-template/src/base-repo/scripts/clean b/apps/github-repository-template/src/base-repo/scripts/clean index cee85198..419c457f 100755 --- a/apps/github-repository-template/src/base-repo/scripts/clean +++ b/apps/github-repository-template/src/base-repo/scripts/clean @@ -29,7 +29,9 @@ find . \( "${prune[@]}" \) -prune -o \ -type f \( -name '*.pyc' -o -name '*.pyo' \) -exec rm -f {} + # Dependency caches, kept out of the search above so that only these exact -# paths are removed rather than every directory sharing their names. -rm -rf node_modules/.cache target/debug/.fingerprint +# paths are removed rather than every directory sharing their names. The CMake +# binary directory is one by path too: the prune above skips it, since it holds +# fetched dependencies' own trees, so it is removed whole here. +rm -rf node_modules/.cache target/debug/.fingerprint "$CMAKE_BUILD_DIR" echo "Cleaned common generated files and caches. Add project-specific cleanup to scripts/clean." diff --git a/apps/github-repository-template/src/base-repo/scripts/libs/dependabot.sh b/apps/github-repository-template/src/base-repo/scripts/libs/dependabot.sh index 14410134..0aa8623e 100644 --- a/apps/github-repository-template/src/base-repo/scripts/libs/dependabot.sh +++ b/apps/github-repository-template/src/base-repo/scripts/libs/dependabot.sh @@ -43,8 +43,8 @@ # The manifest filenames Dependabot reads, and the package-ecosystem each one # earns: dependabot_ecosystem_of , empty for anything else. # -# Deliberately the same six languages the rest of the template detects, plus -# docker, and the same set the mapping table in +# Deliberately the languages the rest of the template detects, less C and C++, +# plus docker, and the same set the mapping table in # apps/repo-builder/src/references/lifecycle.md states. Anything else recognized # here and nowhere else is a shape no other check can see, so a manifest outside # this list is reported by a /repo-builder flow on its own gate rather than @@ -64,6 +64,9 @@ # nothing; Dockerfile. does, and Dependabot reads it too. An ignore # file named for its Containerfile is not an image pin and maps to nothing. # +# CMakeLists.txt is absent because Dependabot has no CMake ecosystem: a +# FetchContent dependency is a URL and a tag that nothing bumps. +# # go.work and settings.gradle.kts are absent on purpose. They are workspace # files: they say where the modules are, and the modules are what Dependabot # reads. Mapping one would derive an entry at the workspace root, and what diff --git a/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh b/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh index b0565fad..32bb870e 100644 --- a/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh +++ b/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh @@ -35,13 +35,17 @@ source "$(dirname "${BASH_SOURCE[0]}")/result.sh" # The single place the supported set is written down. Callers iterate this # rather than keeping their own list. -DETECT_LANGUAGES=(node python go rust swift kotlin) +DETECT_LANGUAGES=(node python go rust swift kotlin cpp) has_node() { [[ -s package.json ]]; } has_python() { [[ -s pyproject.toml ]]; } has_go() { [[ -s go.mod || -s go.work ]]; } has_rust() { [[ -s Cargo.toml ]]; } has_kotlin() { [[ -s settings.gradle.kts || -s build.gradle.kts ]]; } +# C, C++ and assembly are one language here because one build file holds all +# three: CMake compiles a target's .c, .cpp and .S sources together, and the +# checks below read that one project. +has_cpp() { [[ -s CMakeLists.txt ]]; } # Directories holding manifests that belong to a dependency or another # repository rather than to this one. Searching them reports another project's @@ -51,6 +55,14 @@ has_kotlin() { [[ -s settings.gradle.kts || -s build.gradle.kts ]]; } # every check that walks the tree. DETECT_PRUNE_DIRS=(.git node_modules .build target .venv venv vendor tmp) +# The CMake binary directory every C and C++ check configures into. It sits +# where clangd looks for compile_commands.json, and /build/ is already +# gitignored. It is pruned by path rather than joining the names above: +# FetchContent clones each dependency's whole source tree into it, Package.swift +# and CMakeLists.txt included, while a build/ elsewhere may be a source +# package's own name. +CMAKE_BUILD_DIR=build + # DETECT_PRUNE_DIRS as a find(1) `-name a -o -name b ...` expression, assigned # into the array named by $1. Its own copy of this list is the second copy # scripts/clean once kept, and the one this repository's detection module @@ -62,7 +74,7 @@ detect_prune_expr() { for dir in "${DETECT_PRUNE_DIRS[@]}"; do _detect_prune_out+=(-name "$dir" -o) done - unset '_detect_prune_out[${#_detect_prune_out[@]}-1]' + _detect_prune_out+=(-path "./$CMAKE_BUILD_DIR") } # find(1) with the directories above pruned. Arguments after the filename are @@ -232,6 +244,80 @@ go_each() { return "$status" } +# Every C and C++ source and header clang-format should read, NUL-separated, +# with DETECT_PRUNE_DIRS and the CMake binary directory left out. Assembly is +# not listed: clang-format has no assembly mode and reformats it as C. +cpp_sources() { + local prune=() + detect_prune_expr prune + find . \( "${prune[@]}" \) -prune -o -type f \( -name '*.c' -o -name '*.h' \ + -o -name '*.cc' -o -name '*.cpp' -o -name '*.cxx' -o -name '*.hh' \ + -o -name '*.hpp' -o -name '*.hxx' \) -print0 +} + +# Configures the root project into CMAKE_BUILD_DIR, writing the compilation +# database clang-tidy reads. Every check that needs the project calls it rather +# than trusting a build tree left by an earlier run, and a configured tree +# reconfigures in a moment. +cmake_configure() { + command -v cmake >/dev/null 2>&1 || return "$NO_RUNNER" + cmake -S . -B "$CMAKE_BUILD_DIR" --log-level=WARNING -DCMAKE_EXPORT_COMPILE_COMMANDS=ON +} + +cmake_build() { + cmake_configure || return + cmake --build "$CMAKE_BUILD_DIR" --parallel "$(getconf _NPROCESSORS_ONLN)" +} + +# The translation units clang-tidy should read, into the array named by $1: +# the compilation database's files that cpp_sources also lists. That one +# intersection leaves out assembly, which clang-tidy parses as C and fails on, +# sources generated into the binary directory, fetched dependencies, and +# everything pruned. The database names files by physical path, so the +# comparison is made against `pwd -P`; a logical path through a symlink would +# match nothing and lint nothing. +_cmake_translation_units() { + local -n _units_out="$1" + local file root + local -A sources=() + root="$(pwd -P)" + while IFS= read -r -d '' file; do + sources["$root/${file#./}"]=1 + done < <(cpp_sources) + + _units_out=() + while IFS= read -r file; do + # Unset once taken, so a file compiled into two targets is read once. + if [[ -n "${sources[$file]:-}" ]]; then + _units_out+=("$file") + unset 'sources[$file]' + fi + done < <(jq -r '.[].file' "$CMAKE_BUILD_DIR/compile_commands.json") +} + +# clang-tidy over every translation unit, with whatever flags the caller adds. +# Headers are read through the units that include them. +_clang_tidy_project() { + local -a units=() + command -v clang-tidy >/dev/null 2>&1 || return "$NO_RUNNER" + command -v jq >/dev/null 2>&1 || return "$NO_RUNNER" + cmake_configure || return + _cmake_translation_units units + if (( ${#units[@]} == 0 )); then + echo "No C or C++ translation unit in the compilation database." + return 0 + fi + clang-tidy -p "$CMAKE_BUILD_DIR" --quiet "$@" "${units[@]}" +} + +# clang-format over every source, with the caller's mode. +_clang_format_sources() { + local -a files=() + command -v clang-format >/dev/null 2>&1 || return "$NO_RUNNER" + mapfile -d '' files < <(cpp_sources) + (( ${#files[@]} == 0 )) || clang-format "$@" "${files[@]}" +} + # Gradle exposes lint and format tasks only when the matching plugin is applied, # so the task list decides which checks exist. Listing costs a daemon start, so # the result is read once and reused. @@ -299,6 +385,7 @@ detect_orphan_manifests() { "rust:Cargo.toml:Cargo.toml:crate" "go:go.mod:go.work:module" "kotlin:build.gradle.kts:settings.gradle.kts:project" + "cpp:CMakeLists.txt:CMakeLists.txt:project" ) local entry nested_name @@ -327,6 +414,8 @@ detect_orphan_manifests() { "run 'go work init ./$dir' at the repository root" ;; kotlin) _detect_orphan_report "$nested" "$root" "$noun" \ "add a root $root with an include() entry covering $dir" ;; + cpp) _detect_orphan_report "$nested" "$root" "$noun" \ + "add a root $root that reaches $dir through add_subdirectory()" ;; *) _detect_orphan_report "$nested" "$root" "$noun" \ "add a root $root covering $dir" ;; esac @@ -364,6 +453,7 @@ _capability_lint_kotlin() { if gradle_has_task detekt; then ./gradlew detekt; return; fi return "$NO_RUNNER" } +_capability_lint_cpp() { _clang_tidy_project --warnings-as-errors='*'; } _capability_format_check_node() { has_npm_script format:check || return "$NO_RUNNER"; npm run format:check; } _capability_format_check_python() { uv_run ruff format --check --extend-exclude vendor .; } @@ -378,6 +468,7 @@ _capability_format_check_go() { _capability_format_check_rust() { cargo fmt --check; } _capability_format_check_swift() { command -v swift >/dev/null 2>&1 || return "$NO_RUNNER"; swift_each swift format lint --recursive .; } _capability_format_check_kotlin() { gradle_has_task ktlintCheck || return "$NO_RUNNER"; ./gradlew ktlintCheck; } +_capability_format_check_cpp() { _clang_format_sources --dry-run --Werror; } _capability_typecheck_node() { has_npm_script typecheck || return "$NO_RUNNER"; npm run typecheck; } _capability_typecheck_python() { uv_run ty check --exclude '**/vendor/' .; } @@ -389,10 +480,10 @@ _capability_test_node() { has_npm_script test || return "$NO_RUNNER"; npm run te # `scripts/check` out of its integration suite, which is a fix every generated # repository would otherwise have to rediscover. # -# The other four declare their test set instead of discovering it -- an npm -# script, a Gradle source set, a SwiftPM Tests directory, a Cargo test target -- -# so that declaration is what leaves the tier out, and a second exclusion here -# would be a rule with nothing to apply to. +# The other five declare their test set instead of discovering it -- an npm +# script, a Gradle source set, a SwiftPM Tests directory, a Cargo test target, +# a CMake add_test() -- so that declaration is what leaves the tier out, and a +# second exclusion here would be a rule with nothing to apply to. _capability_test_python() { local status=0 dir local -a ignore=() @@ -448,11 +539,28 @@ _capability_test_go() { _capability_test_rust() { cargo test; } _capability_test_swift() { command -v swift >/dev/null 2>&1 || return "$NO_RUNNER"; swift_each swift test; } _capability_test_kotlin() { [[ -x ./gradlew ]] || return "$NO_RUNNER"; ./gradlew test; } +# ctest runs what the build declared, so the tests are built first. A project +# with no add_test() passes with ctest's own "No tests were found", as pytest +# collecting none does. +# +# ctest reads only the top-level CTestTestfile.cmake, which CMake writes only +# when the root CMakeLists.txt calls enable_testing(). Called in a unit's alone, +# every add_test() below it is skipped by that same passing message, so a +# nested test file with no top-level one is refused. +_capability_test_cpp() { + cmake_build || return + if [[ ! -f "$CMAKE_BUILD_DIR/CTestTestfile.cmake" && + -n "$(find "$CMAKE_BUILD_DIR" -name CTestTestfile.cmake -print -quit)" ]]; then + echo "Tests are declared below the root CMakeLists.txt, which never calls enable_testing(), so ctest finds none of them." >&2 + return 1 + fi + ctest --test-dir "$CMAKE_BUILD_DIR" --output-on-failure +} -# The tier's own runners. Absent for rust, swift and kotlin: each names its -# integration tests somewhere its own build file already decides -- a Cargo test -# target, a SwiftPM test target, a Gradle source set -- and a tests/integration/ -# directory is not where any of the three looks. There is no runner for one of +# The tier's own runners. Absent for rust, swift, kotlin and cpp: each names +# its integration tests somewhere its own build file already decides -- a Cargo +# test target, a SwiftPM test target, a Gradle source set, an add_test() -- and +# a tests/integration/ directory is not where any of the four looks. There is no runner for one of # them to be missing, so each reports not-applicable whether or not a tier # exists -- see the arm in _capability_is_not_applicable. _capability_integration_node() { has_npm_script test:integration || return "$NO_RUNNER"; npm run test:integration; } @@ -501,6 +609,7 @@ _capability_build_go() { go_each go build -o /dev/null ./...; } _capability_build_rust() { cargo build --locked; } _capability_build_swift() { command -v swift >/dev/null 2>&1 || return "$NO_RUNNER"; swift_each swift build; } _capability_build_kotlin() { [[ -x ./gradlew ]] || return "$NO_RUNNER"; ./gradlew build -x test; } +_capability_build_cpp() { cmake_build; } _capability_audit_node() { if [[ -s package-lock.json ]] && command -v npm >/dev/null 2>&1; then @@ -545,6 +654,10 @@ _capability_toolchain_kotlin() { command -v java >/dev/null 2>&1 || return "$NO_RUNNER" [[ -x ./gradlew ]] || return "$NO_RUNNER" } +_capability_toolchain_cpp() { + command -v cmake >/dev/null 2>&1 || return "$NO_RUNNER" + command -v ctest >/dev/null 2>&1 || return "$NO_RUNNER" +} _capability_format_write_node() { has_npm_script format || return "$NO_RUNNER"; npm run format; } _capability_format_write_python() { uv_run ruff format --extend-exclude vendor .; } @@ -556,6 +669,7 @@ _capability_format_write_go() { _capability_format_write_rust() { cargo fmt; } _capability_format_write_swift() { command -v swift >/dev/null 2>&1 || return "$NO_RUNNER"; swift_each swift format --in-place --recursive .; } _capability_format_write_kotlin() { gradle_has_task ktlintFormat || return "$NO_RUNNER"; ./gradlew ktlintFormat; } +_capability_format_write_cpp() { _clang_format_sources -i; } # scripts/run resolves the unit's declared run fact into $unit_run and the # arguments after `--` into $unit_args; scripts/package resolves the declared @@ -565,7 +679,7 @@ _capability_format_write_kotlin() { gradle_has_task ktlintFormat || return "$NO_ # # Only one adapter reads the run fact, and that is the trap. In Go, Rust, # Kotlin and Python the command is identical whichever value is declared -- -# Swift has no run adapter at all -- so anyone auditing those concludes +# Swift and C++ have no run adapter at all -- so anyone auditing those concludes # correctly that the branch changes nothing and can be deleted. It cannot: in # Node it chooses between the program's own entry point and a dev server, # which are different programs. @@ -664,6 +778,10 @@ _capability_lint_fix_python() { uv_run ruff check --fix --extend-exclude vendor # and this command is only ever run on one: rewriting the working tree is what # it is for, and the diff is what the operator reviews before committing. _capability_lint_fix_rust() { cargo clippy --fix --allow-dirty --allow-staged; } +# Without --warnings-as-errors, unlike lint: clang-tidy counts a finding it has +# just fixed as an error under that flag, so every successful fix would FAIL. +# Here a leftover finding is printed and the next `lint` fails on it. +_capability_lint_fix_cpp() { _clang_tidy_project --fix; } _capability_run_node() { local line name entries_out chosen i @@ -983,10 +1101,13 @@ _capability_package_rust() { return "$status" } -# No packaging adapter for Node, Python, Swift, or Kotlin, and no run adapter -# for Swift, and each gap is a signpost rather than a mystery: a Node or Python -# executable means bundling an interpreter, and a Swift or Kotlin one means a -# toolchain decision this template has not made. The dispatch reports each as +# No packaging adapter for Node, Python, Swift, Kotlin, or C and C++, and no run +# adapter for Swift or C and C++, and each gap is a signpost rather than a +# mystery: a Node or Python executable means bundling an interpreter, a Swift or +# Kotlin one means a toolchain decision this template has not made, and a C or +# C++ one means reading the unit's executables out of the root project's CMake +# File API, since a unit's CMakeLists.txt is a subdirectory of that project and +# does not configure alone. The dispatch reports each as # `unavailable` and `language_capabilities probe` reports it `absent`, so the # gap is visible without a function standing in for the adapter that is not # there. @@ -1010,7 +1131,7 @@ packaging_writes_dist() { _capability_is_not_applicable() { case "$1:$2" in - typecheck:go|typecheck:rust|typecheck:swift|typecheck:kotlin|build:python) return 0 ;; + typecheck:go|typecheck:rust|typecheck:swift|typecheck:kotlin|typecheck:cpp|build:python) return 0 ;; # No lint autofix exists in any of the three, so there is no tool to install # and nothing for an unavailable to be about. The adapters' own comment has it. lint-fix:go|lint-fix:swift|lint-fix:kotlin) return 0 ;; @@ -1020,13 +1141,17 @@ _capability_is_not_applicable() { # trivy target absent here means nothing to scan, not a missing tool. audit:swift) [[ -z "$(detect_find Package.resolved -print -quit)" ]] ;; audit:kotlin) [[ -z "$(detect_find gradle.lockfile -print -quit)" ]] ;; - # Each of the three names its integration tests where its own build file + # CMake has no lockfile and no advisory database: a FetchContent dependency + # is a URL and a tag in CMakeLists.txt, which nothing scans. A repository + # adopting Conan gains a conan.lock trivy reads, and wires it here. + audit:cpp) return 0 ;; + # Each of the four names its integration tests where its own build file # decides -- a Cargo test target, a SwiftPM Tests directory, a Gradle source - # set -- so tests/integration/ is not a place any of them looks and there is - # no runner for one to be missing. Unconditional, like lint-fix above: an + # set, an add_test() -- so tests/integration/ is not a place any of them + # looks and there is no runner for one to be missing. Unconditional, like lint-fix above: an # unavailable here would fail every Rust repository the moment some other # language in it grew a tier. - integration:rust|integration:swift|integration:kotlin) return 0 ;; + integration:rust|integration:swift|integration:kotlin|integration:cpp) return 0 ;; # A repository with no tier has nothing to run, which is not a missing # runner: every language reports not-applicable rather than one of them # reporting unavailable and failing a run over tests that do not exist. @@ -1139,6 +1264,7 @@ _codeql_entry() { rust) echo 'rust none ubuntu-latest' ;; kotlin) echo 'java-kotlin autobuild ubuntu-latest' ;; swift) echo 'swift autobuild macos-latest' ;; + cpp) echo 'c-cpp none ubuntu-latest' ;; *) return 1 ;; esac } diff --git a/apps/github-repository-template/src/base-repo/scripts/structure b/apps/github-repository-template/src/base-repo/scripts/structure index a1cc788b..e7c15eb1 100755 --- a/apps/github-repository-template/src/base-repo/scripts/structure +++ b/apps/github-repository-template/src/base-repo/scripts/structure @@ -69,6 +69,9 @@ root_files=( package.json package-lock.json tsconfig.json Cargo.toml Cargo.lock build.gradle.kts gradle.properties gradlew gradlew.bat settings.gradle.kts + # clang-format and clang-tidy read no manifest, CMakeLists.txt included, so + # each takes its own file, found by walking up from the source. + CMakeLists.txt .clang-format .clang-tidy ) # Scoped folders: a scope holder -- the repository root, a unit, or a domain -- diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test b/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test index 0da2ba82..693bb9c0 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test @@ -14,7 +14,7 @@ set -uo pipefail # asked of `language_capabilities probe`, and dispatch of `CI_DRY_RUN=1`, which # reports each pairing scripts/ci would run and runs none of them. # -# Covered: the twelve-by-six probe table, dispatch under CI_DRY_RUN=1, and real +# Covered: the twelve-by-seven probe table, dispatch under CI_DRY_RUN=1, and real # runs of ci, security, run, integration, fix, and package against stubbed # toolchains. fix is asked for both halves in order, and a language with no # lint autofix must not fail it. The integration tier's cases run in both @@ -83,7 +83,7 @@ assert_dispatches() { for check in lint format-check typecheck test build; do expected=would-run case "$check:$lang" in - typecheck:go|typecheck:rust|typecheck:swift|typecheck:kotlin|build:python) + typecheck:go|typecheck:rust|typecheck:swift|typecheck:kotlin|typecheck:cpp|build:python) expected=not-applicable ;; esac @@ -108,11 +108,11 @@ assert_absent() { echo "capabilities-test" current="supported languages" -expected=$'node\npython\ngo\nrust\nswift\nkotlin' +expected=$'node\npython\ngo\nrust\nswift\nkotlin\ncpp' if [[ "$(language_capabilities supported)" == "$expected" ]]; then pass else - fail "the interface does not report the six supported languages in order" + fail "the interface does not report the seven supported languages in order" fi # --- every pairing, wired or absent, held as one table ------------------------- @@ -124,14 +124,14 @@ fi # gap the capabilities module explains beside where each would go. Every other # cell is wired, and a `dev` capability no longer exists to have a row at all. current="the probe reports every capability and language pairing" -absent='typecheck:go typecheck:rust typecheck:swift typecheck:kotlin build:python -integration:rust integration:swift integration:kotlin -lint-fix:go lint-fix:swift lint-fix:kotlin -run:swift package:node package:python package:swift package:kotlin' +absent='typecheck:go typecheck:rust typecheck:swift typecheck:kotlin typecheck:cpp build:python +integration:rust integration:swift integration:kotlin integration:cpp +lint-fix:go lint-fix:swift lint-fix:kotlin audit:cpp +run:swift run:cpp package:node package:python package:swift package:kotlin package:cpp' out="$(language_capabilities probe)" missing="" for cap in lint format-check typecheck test build audit toolchain format-write lint-fix integration run package; do - for lang in node python go rust swift kotlin; do + for lang in node python go rust swift kotlin cpp; do expected=wired [[ " ${absent//$'\n'/ } " != *" $cap:$lang "* ]] || expected=absent grep -qE "^$cap +$expected +$lang$" <<<"$out" || missing="$missing $cap:$lang=$expected" @@ -139,8 +139,8 @@ for cap in lint format-check typecheck test build audit toolchain format-write l done if [[ -n "$missing" ]]; then fail "the probe does not report:$missing" -elif (( $(wc -l <<<"$out") != 72 )); then - fail "the probe reports $(wc -l <<<"$out") pairings rather than 72 -- a capability or language it was not asked about" +elif (( $(wc -l <<<"$out") != 84 )); then + fail "the probe reports $(wc -l <<<"$out") pairings rather than 84 -- a capability or language it was not asked about" elif grep -q '^dev ' <<<"$out"; then fail "a dev capability survives in the probe" else @@ -207,6 +207,12 @@ else pass fi +fixture "cmake project" +printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeLists.txt" +out="$(ci)" +assert_dispatches cpp "$out" +assert_absent python "$out" + # --- a manifest no check can see --------------------------------------------- # The failure mode that has no symptom: nothing at the root names this package, @@ -276,6 +282,19 @@ else pass fi +# CMake has no workspace file: the root CMakeLists.txt reaches a unit's through +# add_subdirectory(), so a unit's with none above it is configured by nothing. +fixture "nested CMakeLists.txt, no root" +mkdir -p "$work/apps/fw" +printf 'add_executable(fw src/main.c)\n' > "$work/apps/fw/CMakeLists.txt" +out="$(ci)" +status=$? +if (( status != 0 )) && grep -q "apps/fw/CMakeLists.txt has no root CMakeLists.txt" <<<"$out"; then + pass +else + fail "scripts/ci did not fail naming the orphaned CMakeLists.txt" +fi + # --- root manifest specificity ------------------------------------------------- # has_go accepts go.mod or go.work, and has_kotlin accepts build.gradle.kts or @@ -1008,7 +1027,7 @@ printf '[project]\nname = "p"\nversion = "0.1.0"\n' > "$work/pyproject.toml" output="$(cd "$work" && scripts/detect github-output)" if grep -qx 'python=true' <<<"$output" && grep -qx 'node=false' <<<"$output" && - [[ "$(grep -Ec '^(node|python|go|rust|swift|kotlin)=(true|false)$' <<<"$output")" -eq 6 ]]; then + [[ "$(grep -Ec '^(node|python|go|rust|swift|kotlin|cpp)=(true|false)$' <<<"$output")" -eq 7 ]]; then pass else fail "github-output does not return one boolean for every supported language" @@ -1260,6 +1279,63 @@ else skip "jq is not installed" fi +# clang-tidy is handed the compilation database's units that are this +# repository's own C and C++: not the assembly it parses as C and fails on, not +# a vendored tree, and not a source generated into the binary directory. +fixture "cpp lint reads only the project's own C and C++ units" +if command -v jq >/dev/null 2>&1; then + printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C ASM)\n' > "$work/CMakeLists.txt" + mkdir -p "$work/apps/fw/src" "$work/vendor/lib" + : > "$work/apps/fw/src/main.c" + : > "$work/apps/fw/src/start.S" + : > "$work/vendor/lib/lib.c" + stub cmake <<'STUB' +#!/usr/bin/env bash +root="$(pwd -P)" +mkdir -p build +: > build/gen.c +printf '[{"file":"%s"},{"file":"%s"},{"file":"%s"},{"file":"%s"},{"file":"%s"}]\n' \ + "$root/apps/fw/src/main.c" "$root/apps/fw/src/start.S" "$root/vendor/lib/lib.c" \ + "$root/build/gen.c" "$root/apps/fw/src/main.c" > build/compile_commands.json +STUB + stub clang-tidy <<'STUB' +#!/usr/bin/env bash +printf '%s\n' "$@" > "${MARKER:?}" +STUB + out="$(cd "$work" && MARKER="$work/tidy-args" language_capabilities run lint 2>&1 /dev/null)" + if grep -qE '^lint +pass +cpp$' <<<"$out" && + [[ "$tidy_units" == 1 ]] && grep -qx "$work/apps/fw/src/main.c" "$work/tidy-args"; then + pass + else + fail "clang-tidy was not handed main.c alone, once: $(tr '\n' ' ' < "$work/tidy-args" 2>/dev/null) / $out" + fi +else + skip "jq is not installed" +fi + +# A unit's enable_testing() without the root's leaves ctest reading no test +# file and passing with "No tests were found", so the adapter refuses before +# ctest runs. +fixture "cpp test refuses tests the root never enables" +printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeLists.txt" +stub cmake <<'STUB' +#!/usr/bin/env bash +mkdir -p build/apps/fw +: > build/apps/fw/CTestTestfile.cmake +STUB +stub ctest <<'STUB' +#!/usr/bin/env bash +: > "${MARKER:?}" +STUB +out="$(cd "$work" && MARKER="$work/ctest-ran" language_capabilities run test 2>&1 "$work/build/CMakeCache.txt" +(cd "$work" && scripts/clean) >/dev/null 2>&1 +if [[ ! -d "$work/build" ]]; then + pass +else + fail "scripts/clean left the root build/ in place" +fi + report diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/unit-commands-test b/apps/github-repository-template/src/base-repo/scripts/tests/unit-commands-test index c56bb9fa..89225224 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/unit-commands-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/unit-commands-test @@ -172,7 +172,7 @@ else pass fi -# The other side of the same rule. Four of the six languages have no packaging +# The other side of the same rule. Five of the seven languages have no packaging # adapter, and for a unit in one of those dist/ is not this command's output -- # it holds whatever the unit's own build wrote, which scripts/ci produces before # the release walk reads it. Emptying it there would leave the unit with less diff --git a/apps/repo-builder/src/references/lifecycle.md b/apps/repo-builder/src/references/lifecycle.md index 7d0ce7a6..b46f83d9 100644 --- a/apps/repo-builder/src/references/lifecycle.md +++ b/apps/repo-builder/src/references/lifecycle.md @@ -186,7 +186,7 @@ That is not an exception to the exclusion above: the exclusion stops *language* **An ecosystem outside the table is not derived, and not silently dropped either.** A destination may hold an entry for `terraform`, `nuget`, `bundler`, `docker-compose`, or another the table does not cover, and replacing the file would delete it. So read the destination's copy before replacing it and report every uncovered `package-ecosystem` by name on the flow's own gate; reinstating it is the destination's to authorize. The same goes for an entry under a table ecosystem whose directory the derivation did not produce — a `docker` entry over a `Dockerfile-prod` or Kubernetes or Helm YAML, which that ecosystem also reads — reported by ecosystem and directory. -The table points the other way too. A tracked manifest whose filename it does not list — a Groovy `build.gradle`, a `requirements.txt` or `setup.py` — earns no entry. Do not widen the table: the six languages match the template's language vocabulary and `scripts/libs/detect.sh`, and `docker` is there because the layout names a place for its files. Report it on the same gate, by path, as a manifest Dependabot is not watching and why, for a person to decide whether the repository should carry that shape. +The table points the other way too. A tracked manifest whose filename it does not list — a Groovy `build.gradle`, a `requirements.txt` or `setup.py` — earns no entry. Do not widen the table: its languages are `scripts/libs/detect.sh`'s, less `cpp`, and `docker` is there because the layout names a place for its files. `CMakeLists.txt` has no row because Dependabot has no CMake ecosystem, so a `FetchContent` pin is one nothing bumps; report it like any other unlisted manifest. Report it on the same gate, by path, as a manifest Dependabot is not watching and why, for a person to decide whether the repository should carry that shape. **A derived entry carries the policy the payload's own entries carry** — `interval: weekly`, `cooldown.default-days: 7`, and one group matching `*` named for the ecosystem — so only its origin differs from a shipped one. @@ -224,6 +224,7 @@ The check surface dispatches per language, reads no record, and holds no exempti - **go** — none. `go vet`, `gofmt`, `go test`, and `go build` ship with the toolchain. - **rust** — none. `cargo clippy`, `cargo fmt`, `cargo test`, and `cargo build` come from the toolchain and its rustup components. - **swift** — none. `swift format`, `swift test`, and `swift build` are the compiler's own subcommands. +- **cpp** — `enable_testing()` in the root `CMakeLists.txt` once any `add_test()` exists below it. ctest reads only the top-level test file, which CMake writes only then, so the test check fails a nested one the root never enables. `cmake`, `ctest`, `clang-format`, and `clang-tidy` are `PATH` lookups. The empty three are stated so they do not read as an oversight. diff --git a/docs/adrs/0011-support-c-cpp-and-assembly-as-one-cmake-language.md b/docs/adrs/0011-support-c-cpp-and-assembly-as-one-cmake-language.md new file mode 100644 index 00000000..314a3928 --- /dev/null +++ b/docs/adrs/0011-support-c-cpp-and-assembly-as-one-cmake-language.md @@ -0,0 +1,108 @@ +--- +type: Architecture Decision Record +title: Support C, C++ and Assembly as One Language Built by CMake +description: C, C++ and assembly join the supported set as one detected language, cpp, present when the root holds a CMakeLists.txt, with clang-tidy, clang-format, CMake and ctest as its adapters and the firmware ship targets left until a firmware unit exists. +scope: [global] +tags: [language-support, lang:cpp] +generated: { by: "agent/claude-opus-5-5", at: "2026-11-18T18:08:39Z" } +superseded_by: +status: accepted +--- + +# Support C, C++ and Assembly as One Language Built by CMake + +## Decision + +C, C++ and assembly are one entry in `DETECT_LANGUAGES`, `cpp`, present +when the root holds a non-empty `CMakeLists.txt`. Its adapters are: + +- **lint**: clang-tidy over the compilation database CMake exports, + narrowed to the repository's own C and C++ files. **lint-fix** runs the + same with `--fix`. +- **format-check** and **format-write**: clang-format over the same files. +- **build**: `cmake --build` into the root `build/`. +- **test**: ctest, after a build. +- **toolchain**: checks for `cmake` and `ctest`. +- **CodeQL**: `c-cpp` with `build-mode: none`. + +typecheck, audit and integration are not applicable. run and package are +left absent, so `scripts/run` and `scripts/package` report `unavailable` +for a C or C++ unit. The ship targets a firmware unit needs are not +decided here: they wait until a firmware unit exists to decide them +against. + +## Context + +The template supported six languages, and C, C++ and assembly were rows 7, 8 +and 17 of `docs/language-ranking.md`, each to be added "only when that +specific kind of project comes up". Microcontroller firmware is that +project. A firmware tree mixes all three in one target: a startup file in +assembly, a HAL in C, application code in C or C++. One build file compiles +them together, and CodeQL treats C and C++ as the one language `c-cpp`. So +three detected languages would mean three detectors over one file, and +three columns of adapters that could not differ. + +CMake is the build system because the checks need things only it reports: + +- `CMAKE_EXPORT_COMPILE_COMMANDS` writes `compile_commands.json`, which is + how clang-tidy learns each file's flags and include paths. +- `enable_testing()` and `add_test()` give ctest a test set to run. +- The File API (`build/.cmake/api/v1/reply/`) lists every target with its + type, which is what a later run or package adapter will read to find the + executables. + +The tools ship on GitHub's Ubuntu 24.04 image: CMake 3.31, gcc 13, and +clang, clang-format and clang-tidy 16 to 18. That puts nothing in the setup +action but a check that they are there. + +Three behaviours shaped the adapters, each found by probing: + +- clang-tidy parses `.S` as C and fails, and clang-format has no assembly + mode. Both tools are therefore handed the compilation database + intersected with the repository's own `.c`/`.cc`/`.cpp`-family files. + That one intersection also drops vendored code and sources generated + into, or fetched into, `build/`. +- ctest reads only the top-level `CTestTestfile.cmake`, which CMake writes + only when the root `CMakeLists.txt` calls `enable_testing()`. When only a + unit calls it, ctest prints "No tests were found" and exits 0, so tests + that were written are silently skipped. The test adapter fails when a + nested test file exists and the top-level one does not. A project with + no tests at all still passes, as pytest collecting none does. +- `FetchContent` clones each dependency's tree into `build/`, so the root + `build/` is pruned from every search, and `scripts/clean` removes it by + path. + +## Alternatives Considered + +**GNU Make.** Rejected because it reports nothing the checks need. Make has +no compilation database without wrapping the build in a tool like Bear, no +test registry, and no way to list its executables, so lint, test, run and +package would each need a list that every repository declares and keeps up +to date by hand. This would be worth revisiting if a firmware vendor's SDK +can only be driven by Make. A CMake project can still invoke such a build +through `ExternalProject`. + +**C, C++ and assembly as separate languages.** Rejected for the reasons in +Context: they share one build file, and CodeQL already counts C and C++ as +one language. + +**Wiring run and package now.** Deferred. The File API makes finding +executables cheap, but a host executable and a firmware image are delivered +differently, and the target vocabulary has no word for a microcontroller +yet. Choosing that vocabulary before a firmware unit exists would mean +guessing. + +## Consequences + +- Dependabot has no CMake ecosystem, so a `FetchContent` pin is a URL and a + tag that nothing bumps, and `scripts/security` has no C or C++ audit. + A repository that adopts vcpkg or Conan can add Dependabot's `vcpkg` + ecosystem, or Trivy's Conan support, when that happens. +- `scripts/run` and `scripts/package` fail for a C or C++ unit, which is the + same honest gap Swift's run has, until the firmware decision is made. +- The root `CMakeLists.txt` is the workspace file. A nested one that the + root does not reach is reported by `detect_orphan_manifests`, the same + way a Go module missing from `go.work` is. +- Neither clang-tidy nor clang-format reads a manifest. `.clang-format` and + `.clang-tidy` are therefore permitted at the root by name, and without + them each tool uses its built-in defaults. diff --git a/docs/adrs/index.md b/docs/adrs/index.md index 305c9492..f9b9ea65 100644 --- a/docs/adrs/index.md +++ b/docs/adrs/index.md @@ -14,3 +14,4 @@ | [0008](0008-name-opaque-and-toolchain-folders.md) | Name the Folders a Repository Needs Beyond Its Code, and Let Tools Fix the Rest by Table | proposed | | [0009](0009-name-ticket-categories-after-commit-types.md) | Name Ticket Categories After Conventional Commit Types | accepted | | [0010](0010-run-generates-fixed-steps-as-commands.md) | Run Generate's Fixed Steps as Commands and Keep Their Reasoning Out of the Run | accepted | +| [0011](0011-support-c-cpp-and-assembly-as-one-cmake-language.md) | Support C, C++ and Assembly as One Language Built by CMake | accepted | diff --git a/docs/language-ranking.md b/docs/language-ranking.md index 35c188f3..764ba4be 100644 --- a/docs/language-ranking.md +++ b/docs/language-ranking.md @@ -25,4 +25,4 @@ If you could keep only N languages for all projects, keep the first N rows. Each | 19 | Ruby | Extending existing tools: Homebrew formulas, Rails apps, Metasploit modules. | | 20 | Solidity | Smart contracts on Ethereum and other EVM chains. | -Rows 1–6 are the six languages this template supports. From row 7 on, each language is worth adding only when that specific kind of project comes up. +Rows 1–8 and row 17 are the languages this template supports: C, C++ and assembly as one language, `cpp`, built by CMake (`docs/adrs/0011-support-c-cpp-and-assembly-as-one-cmake-language.md`). From row 9 on, each language is worth adding only when that specific kind of project comes up. diff --git a/scripts/clean b/scripts/clean index cee85198..419c457f 100755 --- a/scripts/clean +++ b/scripts/clean @@ -29,7 +29,9 @@ find . \( "${prune[@]}" \) -prune -o \ -type f \( -name '*.pyc' -o -name '*.pyo' \) -exec rm -f {} + # Dependency caches, kept out of the search above so that only these exact -# paths are removed rather than every directory sharing their names. -rm -rf node_modules/.cache target/debug/.fingerprint +# paths are removed rather than every directory sharing their names. The CMake +# binary directory is one by path too: the prune above skips it, since it holds +# fetched dependencies' own trees, so it is removed whole here. +rm -rf node_modules/.cache target/debug/.fingerprint "$CMAKE_BUILD_DIR" echo "Cleaned common generated files and caches. Add project-specific cleanup to scripts/clean." diff --git a/scripts/libs/dependabot.sh b/scripts/libs/dependabot.sh index 14410134..0aa8623e 100644 --- a/scripts/libs/dependabot.sh +++ b/scripts/libs/dependabot.sh @@ -43,8 +43,8 @@ # The manifest filenames Dependabot reads, and the package-ecosystem each one # earns: dependabot_ecosystem_of , empty for anything else. # -# Deliberately the same six languages the rest of the template detects, plus -# docker, and the same set the mapping table in +# Deliberately the languages the rest of the template detects, less C and C++, +# plus docker, and the same set the mapping table in # apps/repo-builder/src/references/lifecycle.md states. Anything else recognized # here and nowhere else is a shape no other check can see, so a manifest outside # this list is reported by a /repo-builder flow on its own gate rather than @@ -64,6 +64,9 @@ # nothing; Dockerfile. does, and Dependabot reads it too. An ignore # file named for its Containerfile is not an image pin and maps to nothing. # +# CMakeLists.txt is absent because Dependabot has no CMake ecosystem: a +# FetchContent dependency is a URL and a tag that nothing bumps. +# # go.work and settings.gradle.kts are absent on purpose. They are workspace # files: they say where the modules are, and the modules are what Dependabot # reads. Mapping one would derive an entry at the workspace root, and what diff --git a/scripts/libs/detect.sh b/scripts/libs/detect.sh index b0565fad..32bb870e 100644 --- a/scripts/libs/detect.sh +++ b/scripts/libs/detect.sh @@ -35,13 +35,17 @@ source "$(dirname "${BASH_SOURCE[0]}")/result.sh" # The single place the supported set is written down. Callers iterate this # rather than keeping their own list. -DETECT_LANGUAGES=(node python go rust swift kotlin) +DETECT_LANGUAGES=(node python go rust swift kotlin cpp) has_node() { [[ -s package.json ]]; } has_python() { [[ -s pyproject.toml ]]; } has_go() { [[ -s go.mod || -s go.work ]]; } has_rust() { [[ -s Cargo.toml ]]; } has_kotlin() { [[ -s settings.gradle.kts || -s build.gradle.kts ]]; } +# C, C++ and assembly are one language here because one build file holds all +# three: CMake compiles a target's .c, .cpp and .S sources together, and the +# checks below read that one project. +has_cpp() { [[ -s CMakeLists.txt ]]; } # Directories holding manifests that belong to a dependency or another # repository rather than to this one. Searching them reports another project's @@ -51,6 +55,14 @@ has_kotlin() { [[ -s settings.gradle.kts || -s build.gradle.kts ]]; } # every check that walks the tree. DETECT_PRUNE_DIRS=(.git node_modules .build target .venv venv vendor tmp) +# The CMake binary directory every C and C++ check configures into. It sits +# where clangd looks for compile_commands.json, and /build/ is already +# gitignored. It is pruned by path rather than joining the names above: +# FetchContent clones each dependency's whole source tree into it, Package.swift +# and CMakeLists.txt included, while a build/ elsewhere may be a source +# package's own name. +CMAKE_BUILD_DIR=build + # DETECT_PRUNE_DIRS as a find(1) `-name a -o -name b ...` expression, assigned # into the array named by $1. Its own copy of this list is the second copy # scripts/clean once kept, and the one this repository's detection module @@ -62,7 +74,7 @@ detect_prune_expr() { for dir in "${DETECT_PRUNE_DIRS[@]}"; do _detect_prune_out+=(-name "$dir" -o) done - unset '_detect_prune_out[${#_detect_prune_out[@]}-1]' + _detect_prune_out+=(-path "./$CMAKE_BUILD_DIR") } # find(1) with the directories above pruned. Arguments after the filename are @@ -232,6 +244,80 @@ go_each() { return "$status" } +# Every C and C++ source and header clang-format should read, NUL-separated, +# with DETECT_PRUNE_DIRS and the CMake binary directory left out. Assembly is +# not listed: clang-format has no assembly mode and reformats it as C. +cpp_sources() { + local prune=() + detect_prune_expr prune + find . \( "${prune[@]}" \) -prune -o -type f \( -name '*.c' -o -name '*.h' \ + -o -name '*.cc' -o -name '*.cpp' -o -name '*.cxx' -o -name '*.hh' \ + -o -name '*.hpp' -o -name '*.hxx' \) -print0 +} + +# Configures the root project into CMAKE_BUILD_DIR, writing the compilation +# database clang-tidy reads. Every check that needs the project calls it rather +# than trusting a build tree left by an earlier run, and a configured tree +# reconfigures in a moment. +cmake_configure() { + command -v cmake >/dev/null 2>&1 || return "$NO_RUNNER" + cmake -S . -B "$CMAKE_BUILD_DIR" --log-level=WARNING -DCMAKE_EXPORT_COMPILE_COMMANDS=ON +} + +cmake_build() { + cmake_configure || return + cmake --build "$CMAKE_BUILD_DIR" --parallel "$(getconf _NPROCESSORS_ONLN)" +} + +# The translation units clang-tidy should read, into the array named by $1: +# the compilation database's files that cpp_sources also lists. That one +# intersection leaves out assembly, which clang-tidy parses as C and fails on, +# sources generated into the binary directory, fetched dependencies, and +# everything pruned. The database names files by physical path, so the +# comparison is made against `pwd -P`; a logical path through a symlink would +# match nothing and lint nothing. +_cmake_translation_units() { + local -n _units_out="$1" + local file root + local -A sources=() + root="$(pwd -P)" + while IFS= read -r -d '' file; do + sources["$root/${file#./}"]=1 + done < <(cpp_sources) + + _units_out=() + while IFS= read -r file; do + # Unset once taken, so a file compiled into two targets is read once. + if [[ -n "${sources[$file]:-}" ]]; then + _units_out+=("$file") + unset 'sources[$file]' + fi + done < <(jq -r '.[].file' "$CMAKE_BUILD_DIR/compile_commands.json") +} + +# clang-tidy over every translation unit, with whatever flags the caller adds. +# Headers are read through the units that include them. +_clang_tidy_project() { + local -a units=() + command -v clang-tidy >/dev/null 2>&1 || return "$NO_RUNNER" + command -v jq >/dev/null 2>&1 || return "$NO_RUNNER" + cmake_configure || return + _cmake_translation_units units + if (( ${#units[@]} == 0 )); then + echo "No C or C++ translation unit in the compilation database." + return 0 + fi + clang-tidy -p "$CMAKE_BUILD_DIR" --quiet "$@" "${units[@]}" +} + +# clang-format over every source, with the caller's mode. +_clang_format_sources() { + local -a files=() + command -v clang-format >/dev/null 2>&1 || return "$NO_RUNNER" + mapfile -d '' files < <(cpp_sources) + (( ${#files[@]} == 0 )) || clang-format "$@" "${files[@]}" +} + # Gradle exposes lint and format tasks only when the matching plugin is applied, # so the task list decides which checks exist. Listing costs a daemon start, so # the result is read once and reused. @@ -299,6 +385,7 @@ detect_orphan_manifests() { "rust:Cargo.toml:Cargo.toml:crate" "go:go.mod:go.work:module" "kotlin:build.gradle.kts:settings.gradle.kts:project" + "cpp:CMakeLists.txt:CMakeLists.txt:project" ) local entry nested_name @@ -327,6 +414,8 @@ detect_orphan_manifests() { "run 'go work init ./$dir' at the repository root" ;; kotlin) _detect_orphan_report "$nested" "$root" "$noun" \ "add a root $root with an include() entry covering $dir" ;; + cpp) _detect_orphan_report "$nested" "$root" "$noun" \ + "add a root $root that reaches $dir through add_subdirectory()" ;; *) _detect_orphan_report "$nested" "$root" "$noun" \ "add a root $root covering $dir" ;; esac @@ -364,6 +453,7 @@ _capability_lint_kotlin() { if gradle_has_task detekt; then ./gradlew detekt; return; fi return "$NO_RUNNER" } +_capability_lint_cpp() { _clang_tidy_project --warnings-as-errors='*'; } _capability_format_check_node() { has_npm_script format:check || return "$NO_RUNNER"; npm run format:check; } _capability_format_check_python() { uv_run ruff format --check --extend-exclude vendor .; } @@ -378,6 +468,7 @@ _capability_format_check_go() { _capability_format_check_rust() { cargo fmt --check; } _capability_format_check_swift() { command -v swift >/dev/null 2>&1 || return "$NO_RUNNER"; swift_each swift format lint --recursive .; } _capability_format_check_kotlin() { gradle_has_task ktlintCheck || return "$NO_RUNNER"; ./gradlew ktlintCheck; } +_capability_format_check_cpp() { _clang_format_sources --dry-run --Werror; } _capability_typecheck_node() { has_npm_script typecheck || return "$NO_RUNNER"; npm run typecheck; } _capability_typecheck_python() { uv_run ty check --exclude '**/vendor/' .; } @@ -389,10 +480,10 @@ _capability_test_node() { has_npm_script test || return "$NO_RUNNER"; npm run te # `scripts/check` out of its integration suite, which is a fix every generated # repository would otherwise have to rediscover. # -# The other four declare their test set instead of discovering it -- an npm -# script, a Gradle source set, a SwiftPM Tests directory, a Cargo test target -- -# so that declaration is what leaves the tier out, and a second exclusion here -# would be a rule with nothing to apply to. +# The other five declare their test set instead of discovering it -- an npm +# script, a Gradle source set, a SwiftPM Tests directory, a Cargo test target, +# a CMake add_test() -- so that declaration is what leaves the tier out, and a +# second exclusion here would be a rule with nothing to apply to. _capability_test_python() { local status=0 dir local -a ignore=() @@ -448,11 +539,28 @@ _capability_test_go() { _capability_test_rust() { cargo test; } _capability_test_swift() { command -v swift >/dev/null 2>&1 || return "$NO_RUNNER"; swift_each swift test; } _capability_test_kotlin() { [[ -x ./gradlew ]] || return "$NO_RUNNER"; ./gradlew test; } +# ctest runs what the build declared, so the tests are built first. A project +# with no add_test() passes with ctest's own "No tests were found", as pytest +# collecting none does. +# +# ctest reads only the top-level CTestTestfile.cmake, which CMake writes only +# when the root CMakeLists.txt calls enable_testing(). Called in a unit's alone, +# every add_test() below it is skipped by that same passing message, so a +# nested test file with no top-level one is refused. +_capability_test_cpp() { + cmake_build || return + if [[ ! -f "$CMAKE_BUILD_DIR/CTestTestfile.cmake" && + -n "$(find "$CMAKE_BUILD_DIR" -name CTestTestfile.cmake -print -quit)" ]]; then + echo "Tests are declared below the root CMakeLists.txt, which never calls enable_testing(), so ctest finds none of them." >&2 + return 1 + fi + ctest --test-dir "$CMAKE_BUILD_DIR" --output-on-failure +} -# The tier's own runners. Absent for rust, swift and kotlin: each names its -# integration tests somewhere its own build file already decides -- a Cargo test -# target, a SwiftPM test target, a Gradle source set -- and a tests/integration/ -# directory is not where any of the three looks. There is no runner for one of +# The tier's own runners. Absent for rust, swift, kotlin and cpp: each names +# its integration tests somewhere its own build file already decides -- a Cargo +# test target, a SwiftPM test target, a Gradle source set, an add_test() -- and +# a tests/integration/ directory is not where any of the four looks. There is no runner for one of # them to be missing, so each reports not-applicable whether or not a tier # exists -- see the arm in _capability_is_not_applicable. _capability_integration_node() { has_npm_script test:integration || return "$NO_RUNNER"; npm run test:integration; } @@ -501,6 +609,7 @@ _capability_build_go() { go_each go build -o /dev/null ./...; } _capability_build_rust() { cargo build --locked; } _capability_build_swift() { command -v swift >/dev/null 2>&1 || return "$NO_RUNNER"; swift_each swift build; } _capability_build_kotlin() { [[ -x ./gradlew ]] || return "$NO_RUNNER"; ./gradlew build -x test; } +_capability_build_cpp() { cmake_build; } _capability_audit_node() { if [[ -s package-lock.json ]] && command -v npm >/dev/null 2>&1; then @@ -545,6 +654,10 @@ _capability_toolchain_kotlin() { command -v java >/dev/null 2>&1 || return "$NO_RUNNER" [[ -x ./gradlew ]] || return "$NO_RUNNER" } +_capability_toolchain_cpp() { + command -v cmake >/dev/null 2>&1 || return "$NO_RUNNER" + command -v ctest >/dev/null 2>&1 || return "$NO_RUNNER" +} _capability_format_write_node() { has_npm_script format || return "$NO_RUNNER"; npm run format; } _capability_format_write_python() { uv_run ruff format --extend-exclude vendor .; } @@ -556,6 +669,7 @@ _capability_format_write_go() { _capability_format_write_rust() { cargo fmt; } _capability_format_write_swift() { command -v swift >/dev/null 2>&1 || return "$NO_RUNNER"; swift_each swift format --in-place --recursive .; } _capability_format_write_kotlin() { gradle_has_task ktlintFormat || return "$NO_RUNNER"; ./gradlew ktlintFormat; } +_capability_format_write_cpp() { _clang_format_sources -i; } # scripts/run resolves the unit's declared run fact into $unit_run and the # arguments after `--` into $unit_args; scripts/package resolves the declared @@ -565,7 +679,7 @@ _capability_format_write_kotlin() { gradle_has_task ktlintFormat || return "$NO_ # # Only one adapter reads the run fact, and that is the trap. In Go, Rust, # Kotlin and Python the command is identical whichever value is declared -- -# Swift has no run adapter at all -- so anyone auditing those concludes +# Swift and C++ have no run adapter at all -- so anyone auditing those concludes # correctly that the branch changes nothing and can be deleted. It cannot: in # Node it chooses between the program's own entry point and a dev server, # which are different programs. @@ -664,6 +778,10 @@ _capability_lint_fix_python() { uv_run ruff check --fix --extend-exclude vendor # and this command is only ever run on one: rewriting the working tree is what # it is for, and the diff is what the operator reviews before committing. _capability_lint_fix_rust() { cargo clippy --fix --allow-dirty --allow-staged; } +# Without --warnings-as-errors, unlike lint: clang-tidy counts a finding it has +# just fixed as an error under that flag, so every successful fix would FAIL. +# Here a leftover finding is printed and the next `lint` fails on it. +_capability_lint_fix_cpp() { _clang_tidy_project --fix; } _capability_run_node() { local line name entries_out chosen i @@ -983,10 +1101,13 @@ _capability_package_rust() { return "$status" } -# No packaging adapter for Node, Python, Swift, or Kotlin, and no run adapter -# for Swift, and each gap is a signpost rather than a mystery: a Node or Python -# executable means bundling an interpreter, and a Swift or Kotlin one means a -# toolchain decision this template has not made. The dispatch reports each as +# No packaging adapter for Node, Python, Swift, Kotlin, or C and C++, and no run +# adapter for Swift or C and C++, and each gap is a signpost rather than a +# mystery: a Node or Python executable means bundling an interpreter, a Swift or +# Kotlin one means a toolchain decision this template has not made, and a C or +# C++ one means reading the unit's executables out of the root project's CMake +# File API, since a unit's CMakeLists.txt is a subdirectory of that project and +# does not configure alone. The dispatch reports each as # `unavailable` and `language_capabilities probe` reports it `absent`, so the # gap is visible without a function standing in for the adapter that is not # there. @@ -1010,7 +1131,7 @@ packaging_writes_dist() { _capability_is_not_applicable() { case "$1:$2" in - typecheck:go|typecheck:rust|typecheck:swift|typecheck:kotlin|build:python) return 0 ;; + typecheck:go|typecheck:rust|typecheck:swift|typecheck:kotlin|typecheck:cpp|build:python) return 0 ;; # No lint autofix exists in any of the three, so there is no tool to install # and nothing for an unavailable to be about. The adapters' own comment has it. lint-fix:go|lint-fix:swift|lint-fix:kotlin) return 0 ;; @@ -1020,13 +1141,17 @@ _capability_is_not_applicable() { # trivy target absent here means nothing to scan, not a missing tool. audit:swift) [[ -z "$(detect_find Package.resolved -print -quit)" ]] ;; audit:kotlin) [[ -z "$(detect_find gradle.lockfile -print -quit)" ]] ;; - # Each of the three names its integration tests where its own build file + # CMake has no lockfile and no advisory database: a FetchContent dependency + # is a URL and a tag in CMakeLists.txt, which nothing scans. A repository + # adopting Conan gains a conan.lock trivy reads, and wires it here. + audit:cpp) return 0 ;; + # Each of the four names its integration tests where its own build file # decides -- a Cargo test target, a SwiftPM Tests directory, a Gradle source - # set -- so tests/integration/ is not a place any of them looks and there is - # no runner for one to be missing. Unconditional, like lint-fix above: an + # set, an add_test() -- so tests/integration/ is not a place any of them + # looks and there is no runner for one to be missing. Unconditional, like lint-fix above: an # unavailable here would fail every Rust repository the moment some other # language in it grew a tier. - integration:rust|integration:swift|integration:kotlin) return 0 ;; + integration:rust|integration:swift|integration:kotlin|integration:cpp) return 0 ;; # A repository with no tier has nothing to run, which is not a missing # runner: every language reports not-applicable rather than one of them # reporting unavailable and failing a run over tests that do not exist. @@ -1139,6 +1264,7 @@ _codeql_entry() { rust) echo 'rust none ubuntu-latest' ;; kotlin) echo 'java-kotlin autobuild ubuntu-latest' ;; swift) echo 'swift autobuild macos-latest' ;; + cpp) echo 'c-cpp none ubuntu-latest' ;; *) return 1 ;; esac } diff --git a/scripts/structure b/scripts/structure index a1cc788b..e7c15eb1 100755 --- a/scripts/structure +++ b/scripts/structure @@ -69,6 +69,9 @@ root_files=( package.json package-lock.json tsconfig.json Cargo.toml Cargo.lock build.gradle.kts gradle.properties gradlew gradlew.bat settings.gradle.kts + # clang-format and clang-tidy read no manifest, CMakeLists.txt included, so + # each takes its own file, found by walking up from the source. + CMakeLists.txt .clang-format .clang-tidy ) # Scoped folders: a scope holder -- the repository root, a unit, or a domain -- diff --git a/scripts/tests/capabilities-test b/scripts/tests/capabilities-test index 0da2ba82..693bb9c0 100755 --- a/scripts/tests/capabilities-test +++ b/scripts/tests/capabilities-test @@ -14,7 +14,7 @@ set -uo pipefail # asked of `language_capabilities probe`, and dispatch of `CI_DRY_RUN=1`, which # reports each pairing scripts/ci would run and runs none of them. # -# Covered: the twelve-by-six probe table, dispatch under CI_DRY_RUN=1, and real +# Covered: the twelve-by-seven probe table, dispatch under CI_DRY_RUN=1, and real # runs of ci, security, run, integration, fix, and package against stubbed # toolchains. fix is asked for both halves in order, and a language with no # lint autofix must not fail it. The integration tier's cases run in both @@ -83,7 +83,7 @@ assert_dispatches() { for check in lint format-check typecheck test build; do expected=would-run case "$check:$lang" in - typecheck:go|typecheck:rust|typecheck:swift|typecheck:kotlin|build:python) + typecheck:go|typecheck:rust|typecheck:swift|typecheck:kotlin|typecheck:cpp|build:python) expected=not-applicable ;; esac @@ -108,11 +108,11 @@ assert_absent() { echo "capabilities-test" current="supported languages" -expected=$'node\npython\ngo\nrust\nswift\nkotlin' +expected=$'node\npython\ngo\nrust\nswift\nkotlin\ncpp' if [[ "$(language_capabilities supported)" == "$expected" ]]; then pass else - fail "the interface does not report the six supported languages in order" + fail "the interface does not report the seven supported languages in order" fi # --- every pairing, wired or absent, held as one table ------------------------- @@ -124,14 +124,14 @@ fi # gap the capabilities module explains beside where each would go. Every other # cell is wired, and a `dev` capability no longer exists to have a row at all. current="the probe reports every capability and language pairing" -absent='typecheck:go typecheck:rust typecheck:swift typecheck:kotlin build:python -integration:rust integration:swift integration:kotlin -lint-fix:go lint-fix:swift lint-fix:kotlin -run:swift package:node package:python package:swift package:kotlin' +absent='typecheck:go typecheck:rust typecheck:swift typecheck:kotlin typecheck:cpp build:python +integration:rust integration:swift integration:kotlin integration:cpp +lint-fix:go lint-fix:swift lint-fix:kotlin audit:cpp +run:swift run:cpp package:node package:python package:swift package:kotlin package:cpp' out="$(language_capabilities probe)" missing="" for cap in lint format-check typecheck test build audit toolchain format-write lint-fix integration run package; do - for lang in node python go rust swift kotlin; do + for lang in node python go rust swift kotlin cpp; do expected=wired [[ " ${absent//$'\n'/ } " != *" $cap:$lang "* ]] || expected=absent grep -qE "^$cap +$expected +$lang$" <<<"$out" || missing="$missing $cap:$lang=$expected" @@ -139,8 +139,8 @@ for cap in lint format-check typecheck test build audit toolchain format-write l done if [[ -n "$missing" ]]; then fail "the probe does not report:$missing" -elif (( $(wc -l <<<"$out") != 72 )); then - fail "the probe reports $(wc -l <<<"$out") pairings rather than 72 -- a capability or language it was not asked about" +elif (( $(wc -l <<<"$out") != 84 )); then + fail "the probe reports $(wc -l <<<"$out") pairings rather than 84 -- a capability or language it was not asked about" elif grep -q '^dev ' <<<"$out"; then fail "a dev capability survives in the probe" else @@ -207,6 +207,12 @@ else pass fi +fixture "cmake project" +printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeLists.txt" +out="$(ci)" +assert_dispatches cpp "$out" +assert_absent python "$out" + # --- a manifest no check can see --------------------------------------------- # The failure mode that has no symptom: nothing at the root names this package, @@ -276,6 +282,19 @@ else pass fi +# CMake has no workspace file: the root CMakeLists.txt reaches a unit's through +# add_subdirectory(), so a unit's with none above it is configured by nothing. +fixture "nested CMakeLists.txt, no root" +mkdir -p "$work/apps/fw" +printf 'add_executable(fw src/main.c)\n' > "$work/apps/fw/CMakeLists.txt" +out="$(ci)" +status=$? +if (( status != 0 )) && grep -q "apps/fw/CMakeLists.txt has no root CMakeLists.txt" <<<"$out"; then + pass +else + fail "scripts/ci did not fail naming the orphaned CMakeLists.txt" +fi + # --- root manifest specificity ------------------------------------------------- # has_go accepts go.mod or go.work, and has_kotlin accepts build.gradle.kts or @@ -1008,7 +1027,7 @@ printf '[project]\nname = "p"\nversion = "0.1.0"\n' > "$work/pyproject.toml" output="$(cd "$work" && scripts/detect github-output)" if grep -qx 'python=true' <<<"$output" && grep -qx 'node=false' <<<"$output" && - [[ "$(grep -Ec '^(node|python|go|rust|swift|kotlin)=(true|false)$' <<<"$output")" -eq 6 ]]; then + [[ "$(grep -Ec '^(node|python|go|rust|swift|kotlin|cpp)=(true|false)$' <<<"$output")" -eq 7 ]]; then pass else fail "github-output does not return one boolean for every supported language" @@ -1260,6 +1279,63 @@ else skip "jq is not installed" fi +# clang-tidy is handed the compilation database's units that are this +# repository's own C and C++: not the assembly it parses as C and fails on, not +# a vendored tree, and not a source generated into the binary directory. +fixture "cpp lint reads only the project's own C and C++ units" +if command -v jq >/dev/null 2>&1; then + printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C ASM)\n' > "$work/CMakeLists.txt" + mkdir -p "$work/apps/fw/src" "$work/vendor/lib" + : > "$work/apps/fw/src/main.c" + : > "$work/apps/fw/src/start.S" + : > "$work/vendor/lib/lib.c" + stub cmake <<'STUB' +#!/usr/bin/env bash +root="$(pwd -P)" +mkdir -p build +: > build/gen.c +printf '[{"file":"%s"},{"file":"%s"},{"file":"%s"},{"file":"%s"},{"file":"%s"}]\n' \ + "$root/apps/fw/src/main.c" "$root/apps/fw/src/start.S" "$root/vendor/lib/lib.c" \ + "$root/build/gen.c" "$root/apps/fw/src/main.c" > build/compile_commands.json +STUB + stub clang-tidy <<'STUB' +#!/usr/bin/env bash +printf '%s\n' "$@" > "${MARKER:?}" +STUB + out="$(cd "$work" && MARKER="$work/tidy-args" language_capabilities run lint 2>&1 /dev/null)" + if grep -qE '^lint +pass +cpp$' <<<"$out" && + [[ "$tidy_units" == 1 ]] && grep -qx "$work/apps/fw/src/main.c" "$work/tidy-args"; then + pass + else + fail "clang-tidy was not handed main.c alone, once: $(tr '\n' ' ' < "$work/tidy-args" 2>/dev/null) / $out" + fi +else + skip "jq is not installed" +fi + +# A unit's enable_testing() without the root's leaves ctest reading no test +# file and passing with "No tests were found", so the adapter refuses before +# ctest runs. +fixture "cpp test refuses tests the root never enables" +printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeLists.txt" +stub cmake <<'STUB' +#!/usr/bin/env bash +mkdir -p build/apps/fw +: > build/apps/fw/CTestTestfile.cmake +STUB +stub ctest <<'STUB' +#!/usr/bin/env bash +: > "${MARKER:?}" +STUB +out="$(cd "$work" && MARKER="$work/ctest-ran" language_capabilities run test 2>&1 "$work/build/CMakeCache.txt" +(cd "$work" && scripts/clean) >/dev/null 2>&1 +if [[ ! -d "$work/build" ]]; then + pass +else + fail "scripts/clean left the root build/ in place" +fi + report diff --git a/scripts/tests/unit-commands-test b/scripts/tests/unit-commands-test index c56bb9fa..89225224 100755 --- a/scripts/tests/unit-commands-test +++ b/scripts/tests/unit-commands-test @@ -172,7 +172,7 @@ else pass fi -# The other side of the same rule. Four of the six languages have no packaging +# The other side of the same rule. Five of the seven languages have no packaging # adapter, and for a unit in one of those dist/ is not this command's output -- # it holds whatever the unit's own build wrote, which scripts/ci produces before # the release walk reads it. Emptying it there would leave the unit with less From b905b85bf5c3bfb9dc3efd6e22f2f45255f3c398 Mon Sep 17 00:00:00 2001 From: neal Date: Wed, 18 Nov 2026 13:31:56 -0500 Subject: [PATCH 2/3] fix(detect): close the cmake review's gaps in lint, test and orphans Correctness review of #323 found three ways the cpp adapters misreport: - clang-tidy matched compile_commands.json entries against `pwd -P`, but CMake writes the logical path it ran from, so a checkout reached through a symlink linted no units and passed. Entries are now compared relative to either path. - the enable_testing guard fired on any nested CTestTestfile.cmake, including a dependency's under build/_deps that calls include(CTest), failing a project with no tests. It now refuses only a nested file that declares add_test(), outside _deps/ and vendor/. - the orphan search reported every nested CMakeLists.txt in a repository with no root one, including an Android NDK library under src/ or a scikit-build or cmake-js build beside its own manifest, so existing Kotlin, Python and Node repositories would fail detection. Those are now left to the language that owns them. The fourth finding, gcc-only flags reaching clang-tidy as unknown arguments, is recorded as a consequence in ADR 0011 rather than worked around, since choosing the lint compiler is the repository's call. Also applies the standards review's wording fixes: the language counts in scripts/package, dependabot-entries-test and the structure doc, and the Dependabot exception in the adding-a-language rule. Generated-By: claude-opus-5-5 --- CLAUDE.md | 2 +- .../docs/github_repository_structure.md | 2 +- .../src/base-repo/CLAUDE.md | 2 +- .../src/base-repo/scripts/libs/detect.sh | 46 ++++++++++--- .../src/base-repo/scripts/package | 8 +-- .../base-repo/scripts/tests/capabilities-test | 69 ++++++++++++++++++- .../scripts/tests/dependabot-entries-test | 5 +- ...-cpp-and-assembly-as-one-cmake-language.md | 16 ++++- scripts/CLAUDE.md | 2 +- scripts/libs/detect.sh | 46 ++++++++++--- scripts/package | 8 +-- scripts/tests/capabilities-test | 69 ++++++++++++++++++- scripts/tests/dependabot-entries-test | 5 +- 13 files changed, 237 insertions(+), 43 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index bed4a468..e4098b43 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -129,7 +129,7 @@ Reading the file needs `jq`, which `scripts/doctor` requires. Without it the aud Three rules are about content, and no script can settle them: whether `libs/` holds what several apps share, whether `tests/` spans them, and whether a file sits at its own scope. `scripts/structure` reports them `not-applicable` rather than guessing from paths. -A package whose language has no root manifest fails the run, because that manifest is what lists it: `go list -m` names only `go.work`'s `use` entries, the Gradle settings file likewise, and CMake configures only what the root `CMakeLists.txt` reaches through `add_subdirectory()`. Swift is excluded: it has no root manifest, and nested packages are how a Swift repository is meant to look. The failure names the root manifest to add. +A package whose language has no root manifest fails the run, because that manifest is what lists it: `go list -m` names only `go.work`'s `use` entries, the Gradle settings file likewise, and CMake configures only what the root `CMakeLists.txt` reaches through `add_subdirectory()`. Swift is excluded: it has no root manifest, and nested packages are how a Swift repository is meant to look. So is a `CMakeLists.txt` below a `src/` or beside another language's manifest, which belongs to that language's native build. The failure names the root manifest to add. ## Repository settings diff --git a/apps/github-repository-template/docs/github_repository_structure.md b/apps/github-repository-template/docs/github_repository_structure.md index c5e9bac5..ac633a6c 100644 --- a/apps/github-repository-template/docs/github_repository_structure.md +++ b/apps/github-repository-template/docs/github_repository_structure.md @@ -89,7 +89,7 @@ The specific operating parameters for the AI agent. `scripts/fix`: The write half of what `scripts/check` checks, for every detected stack — the linter's own autofix, then the formatting, so what a lint rule rewrites is laid out by the formatter that follows it. Neither half is behind a flag: every autofix reached here is one the tool itself considers safe, withholding the rest as ruff does behind `--unsafe-fixes`, and it is a rewrite the linter would have demanded at the gate anyway. Go, Swift and Kotlin have no lint autofix distinct from their formatter, so `lint-fix` reports those three `not-applicable` rather than `unavailable`: there is no tool to install, and an `unavailable` would fail this command on every Go repository over a gap nothing can close. A `lint-fix` FAIL means findings remain that the tool could not fix itself, which is what every such linter exits non-zero for. -`scripts/integration`: Runs the integration tier — every `tests/integration/` directory in the repository, at whatever scope holder it sits under. The tier is a path the layout owns rather than a marker each language spells its own way, so where an integration test goes is read off the layout rules and not off six idioms. It takes no unit name: a repository whose tiers must run separately runs this from inside the unit. Nothing in the gate calls it, and the `test` capability excludes the tier for the two runners that discover tests by walking the tree, pytest and `go test ./...`. `integration` reports `not-applicable` for every language in a repository that has no tier, and for Rust, Swift and Kotlin whether or not one exists — each names its integration tests somewhere its own build file decides, so `tests/integration/` is not a place any of the three looks and there is no runner for one to be missing. +`scripts/integration`: Runs the integration tier — every `tests/integration/` directory in the repository, at whatever scope holder it sits under. The tier is a path the layout owns rather than a marker each language spells its own way, so where an integration test goes is read off the layout rules and not off seven idioms. It takes no unit name: a repository whose tiers must run separately runs this from inside the unit. Nothing in the gate calls it, and the `test` capability excludes the tier for the two runners that discover tests by walking the tree, pytest and `go test ./...`. `integration` reports `not-applicable` for every language in a repository that has no tier, and for Rust, Swift, Kotlin, and C and C++ whether or not one exists — each names its integration tests somewhere its own build file decides, so `tests/integration/` is not a place any of the four looks and there is no runner for one to be missing. `scripts/release`: Validates a version tag against the changelog, packages every unit under `apps/`, and cuts a GitHub release with whatever those units produced attached. Packaging runs before the tag, so a build that cannot be made publishes nothing; a repository where no unit ships a file still releases. diff --git a/apps/github-repository-template/src/base-repo/CLAUDE.md b/apps/github-repository-template/src/base-repo/CLAUDE.md index c6e9a55c..4550db22 100644 --- a/apps/github-repository-template/src/base-repo/CLAUDE.md +++ b/apps/github-repository-template/src/base-repo/CLAUDE.md @@ -29,7 +29,7 @@ Use these instead of per-language tools. `check` and `fix` run for every languag - `docs/` takes Markdown; anything else there needs `.structure-allow`. - Below a `src/`, an `examples/`, a `vendor/`, or a toolchain folder, that tree's own language or tool decides the layout. - A path ending in `/` in `.structure-allow` exempts that whole prefix, for a tracked fixture tree. -- A package whose language has no root manifest fails the gate; add the root workspace manifest (`go.work`, `settings.gradle.kts`, a `CMakeLists.txt` that reaches it through `add_subdirectory()`, and so on) that lists it. Swift is excepted: it has no root manifest. +- A package whose language has no root manifest fails the gate; add the root workspace manifest (`go.work`, `settings.gradle.kts`, a `CMakeLists.txt` that reaches it through `add_subdirectory()`, and so on) that lists it. Swift is excepted: it has no root manifest. So is a `CMakeLists.txt` below a `src/` or beside another language's manifest, which belongs to that language's native build. These are conventions `scripts/structure` does not check: diff --git a/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh b/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh index 32bb870e..1b4296de 100644 --- a/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh +++ b/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh @@ -273,24 +273,28 @@ cmake_build() { # the compilation database's files that cpp_sources also lists. That one # intersection leaves out assembly, which clang-tidy parses as C and fails on, # sources generated into the binary directory, fetched dependencies, and -# everything pruned. The database names files by physical path, so the -# comparison is made against `pwd -P`; a logical path through a symlink would -# match nothing and lint nothing. +# everything pruned. The database names files by the logical path CMake was +# run from, which is the physical one unless the checkout is reached through a +# symlink, so each entry is compared relative to whichever of the two it starts +# with; matching only one would lint nothing and pass. _cmake_translation_units() { local -n _units_out="$1" - local file root + local file relative logical physical local -A sources=() - root="$(pwd -P)" + logical="${PWD%/}/" + physical="$(pwd -P)/" while IFS= read -r -d '' file; do - sources["$root/${file#./}"]=1 + sources["${file#./}"]=1 done < <(cpp_sources) _units_out=() while IFS= read -r file; do + relative="${file#"$logical"}" + [[ "$relative" != "$file" ]] || relative="${file#"$physical"}" # Unset once taken, so a file compiled into two targets is read once. - if [[ -n "${sources[$file]:-}" ]]; then + if [[ -n "${sources[$relative]:-}" ]]; then _units_out+=("$file") - unset 'sources[$file]' + unset 'sources[$relative]' fi done < <(jq -r '.[].file' "$CMAKE_BUILD_DIR/compile_commands.json") } @@ -373,6 +377,16 @@ _detect_orphan_report() { echo "$nested has no root $root, so no check sees this $noun; $fix, or move it under an existing workspace" } +# Whether the CMakeLists.txt in $1 belongs to another language's build. +_cmake_owned_elsewhere() { + local dir="$1" manifest + [[ "/$dir/" != */src/* ]] || return 0 + for manifest in package.json pyproject.toml Cargo.toml go.mod build.gradle.kts Package.swift; do + [[ ! -e "$dir/$manifest" ]] || return 0 + done + return 1 +} + detect_orphan_manifests() { local lang root nested dir @@ -409,6 +423,12 @@ detect_orphan_manifests() { # without a workspace file, not a nested module missing one. [[ "$dir" != "." ]] || continue + # A CMakeLists.txt is also how other languages build native code: an + # Android NDK library under a Kotlin unit's src/, a scikit-build Python + # package, a cmake-js Node addon. Below a src/, or beside another + # language's manifest, it belongs to that build and needs no root. + if [[ "$lang" == cpp ]] && _cmake_owned_elsewhere "$dir"; then continue; fi + case "$lang" in go) _detect_orphan_report "$nested" "$root" "$noun" \ "run 'go work init ./$dir' at the repository root" ;; @@ -546,11 +566,15 @@ _capability_test_kotlin() { [[ -x ./gradlew ]] || return "$NO_RUNNER"; ./gradlew # ctest reads only the top-level CTestTestfile.cmake, which CMake writes only # when the root CMakeLists.txt calls enable_testing(). Called in a unit's alone, # every add_test() below it is skipped by that same passing message, so a -# nested test file with no top-level one is refused. +# nested test file declaring a test, with no top-level one, is refused. A +# dependency's own test files, fetched into _deps/ or built from vendor/, are +# not this project's tests: a library that calls include(CTest) regardless +# must not fail a project that has none. _capability_test_cpp() { cmake_build || return - if [[ ! -f "$CMAKE_BUILD_DIR/CTestTestfile.cmake" && - -n "$(find "$CMAKE_BUILD_DIR" -name CTestTestfile.cmake -print -quit)" ]]; then + if [[ ! -f "$CMAKE_BUILD_DIR/CTestTestfile.cmake" ]] && + find "$CMAKE_BUILD_DIR" \( -path '*/_deps' -o -path '*/vendor' \) -prune -o \ + -name CTestTestfile.cmake -exec grep -q '^add_test(' {} \; -print | grep -q .; then echo "Tests are declared below the root CMakeLists.txt, which never calls enable_testing(), so ctest finds none of them." >&2 return 1 fi diff --git a/apps/github-repository-template/src/base-repo/scripts/package b/apps/github-repository-template/src/base-repo/scripts/package index d0326db0..5ab85d47 100755 --- a/apps/github-repository-template/src/base-repo/scripts/package +++ b/apps/github-repository-template/src/base-repo/scripts/package @@ -57,10 +57,10 @@ fi # guard was written to prevent, arriving by a route it cannot see. So the # directory is emptied by the dispatch that refills it. # -# Only when a present language actually packages into it. Four of the six have -# no packaging adapter, and for a unit in one of those dist/ holds whatever its -# own build wrote -- which is what scripts/ci produces before the release walk -# reads it. Emptying that would leave the unit with less than it started with +# Only when a present language actually packages into it. Five of the seven +# have no packaging adapter, and for a unit in one of those dist/ holds +# whatever its own build wrote -- which is what scripts/ci produces before the +# release walk reads it. Emptying that would leave the unit with less than it started with # and abort the release it was meant to protect, so packaging_writes_dist is # asked first and the knowledge of which adapters write there stays beside them. # diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test b/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test index 693bb9c0..2a7ea268 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test @@ -295,6 +295,23 @@ else fail "scripts/ci did not fail naming the orphaned CMakeLists.txt" fi +# A CMakeLists.txt below a src/, as an Android NDK library sits in a Kotlin +# unit, or beside another language's manifest, belongs to that build, so only +# the unit's own one is an orphan. +fixture "CMakeLists.txt owned by another build is no orphan" +mkdir -p "$work/apps/fw" "$work/apps/android/src/main/cpp" "$work/apps/ios" +printf 'add_executable(fw src/main.c)\n' > "$work/apps/fw/CMakeLists.txt" +printf 'add_library(jni SHARED jni.c)\n' > "$work/apps/android/src/main/cpp/CMakeLists.txt" +printf 'add_library(native native.c)\n' > "$work/apps/ios/CMakeLists.txt" +printf '// swift-tools-version:5.9\n' > "$work/apps/ios/Package.swift" +out="$(ci)" +if grep -q "apps/fw/CMakeLists.txt has no root" <<<"$out" && + ! grep -q "apps/android/src/main/cpp/CMakeLists.txt\|apps/ios/CMakeLists.txt" <<<"$out"; then + pass +else + fail "the orphan search did not name apps/fw's CMakeLists.txt alone: $out" +fi + # --- root manifest specificity ------------------------------------------------- # has_go accepts go.mod or go.work, and has_kotlin accepts build.gradle.kts or @@ -1314,6 +1331,35 @@ else skip "jq is not installed" fi +# CMake writes the database with the logical path it ran from, so a checkout +# reached through a symlink still lints its own units rather than none. +fixture "cpp lint matches units through a symlinked checkout" +if command -v jq >/dev/null 2>&1; then + printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeLists.txt" + mkdir -p "$work/apps/fw/src" + : > "$work/apps/fw/src/main.c" + ln -s "$work" "$work.link" + stub cmake <<'STUB' +#!/usr/bin/env bash +mkdir -p build +printf '[{"file":"%s"}]\n' "$PWD/apps/fw/src/main.c" > build/compile_commands.json +STUB + stub clang-tidy <<'STUB' +#!/usr/bin/env bash +printf '%s\n' "$@" > "${MARKER:?}" +STUB + out="$(cd "$work.link" && MARKER="$work/tidy-args" language_capabilities run lint 2>&1 /dev/null; then + pass + else + fail "clang-tidy was not handed main.c through the symlink: $out" + fi + rm -f "$work.link" +else + skip "jq is not installed" +fi + # A unit's enable_testing() without the root's leaves ctest reading no test # file and passing with "No tests were found", so the adapter refuses before # ctest runs. @@ -1322,7 +1368,7 @@ printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeList stub cmake <<'STUB' #!/usr/bin/env bash mkdir -p build/apps/fw -: > build/apps/fw/CTestTestfile.cmake +printf 'add_test([=[t]=] "/bin/true")\n' > build/apps/fw/CTestTestfile.cmake STUB stub ctest <<'STUB' #!/usr/bin/env bash @@ -1336,6 +1382,27 @@ else fail "the cpp test adapter did not refuse a nested CTestTestfile.cmake with no root one: $out" fi +# A dependency fetched into _deps/ may call include(CTest) whatever its parent +# does; its tests are not the project's, so a project with none still passes. +fixture "cpp test ignores a dependency's own tests" +printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeLists.txt" +stub cmake <<'STUB' +#!/usr/bin/env bash +mkdir -p build/_deps/dep-build build/apps/fw +printf 'add_test([=[t]=] "/bin/true")\n' > build/_deps/dep-build/CTestTestfile.cmake +printf 'subdirs("x")\n' > build/apps/fw/CTestTestfile.cmake +STUB +stub ctest <<'STUB' +#!/usr/bin/env bash +: > "${MARKER:?}" +STUB +out="$(cd "$work" && MARKER="$work/ctest-ran" language_capabilities run test 2>&1 ` detector, add a `_capability__` function for each capability it can answer (one with no honest adapter is left absent, not stubbed), add a `_codeql_entry` row, add its toolchain to `.github/actions/setup-toolchains/action.yml`, and add its column to the table `tests/capabilities-test` holds against `language_capabilities probe`, naming which cells are deliberately `absent`. That suite is the only thing that notices a dropped language, which otherwise produces a shorter green run. Also add its root workspace manifests and lockfiles to `scripts/structure`'s `root_files`, its nested/root pair to `detect_orphan_manifests`'s `pairs`, and its manifest to `libs/dependabot.sh`'s `dependabot_ecosystem_of`; a language missing from any of the three is rejected at the root, escapes the orphan search, or goes unwatched by Dependabot. +Adding a language: add it to `DETECT_LANGUAGES`, add its `has_` detector, add a `_capability__` function for each capability it can answer (one with no honest adapter is left absent, not stubbed), add a `_codeql_entry` row, add its toolchain to `.github/actions/setup-toolchains/action.yml`, and add its column to the table `tests/capabilities-test` holds against `language_capabilities probe`, naming which cells are deliberately `absent`. That suite is the only thing that notices a dropped language, which otherwise produces a shorter green run. Also add its root workspace manifests and lockfiles to `scripts/structure`'s `root_files`, its nested/root pair to `detect_orphan_manifests`'s `pairs`, and its manifest to `libs/dependabot.sh`'s `dependabot_ecosystem_of` unless Dependabot has no ecosystem for it, as for C and C++; a language missing from any of the three is rejected at the root, escapes the orphan search, or goes unwatched by Dependabot. Adding a check: add it to `DETECT_CAPABILITIES` and write an adapter per language, or declare it not-applicable in `_capability_is_not_applicable`. diff --git a/scripts/libs/detect.sh b/scripts/libs/detect.sh index 32bb870e..1b4296de 100644 --- a/scripts/libs/detect.sh +++ b/scripts/libs/detect.sh @@ -273,24 +273,28 @@ cmake_build() { # the compilation database's files that cpp_sources also lists. That one # intersection leaves out assembly, which clang-tidy parses as C and fails on, # sources generated into the binary directory, fetched dependencies, and -# everything pruned. The database names files by physical path, so the -# comparison is made against `pwd -P`; a logical path through a symlink would -# match nothing and lint nothing. +# everything pruned. The database names files by the logical path CMake was +# run from, which is the physical one unless the checkout is reached through a +# symlink, so each entry is compared relative to whichever of the two it starts +# with; matching only one would lint nothing and pass. _cmake_translation_units() { local -n _units_out="$1" - local file root + local file relative logical physical local -A sources=() - root="$(pwd -P)" + logical="${PWD%/}/" + physical="$(pwd -P)/" while IFS= read -r -d '' file; do - sources["$root/${file#./}"]=1 + sources["${file#./}"]=1 done < <(cpp_sources) _units_out=() while IFS= read -r file; do + relative="${file#"$logical"}" + [[ "$relative" != "$file" ]] || relative="${file#"$physical"}" # Unset once taken, so a file compiled into two targets is read once. - if [[ -n "${sources[$file]:-}" ]]; then + if [[ -n "${sources[$relative]:-}" ]]; then _units_out+=("$file") - unset 'sources[$file]' + unset 'sources[$relative]' fi done < <(jq -r '.[].file' "$CMAKE_BUILD_DIR/compile_commands.json") } @@ -373,6 +377,16 @@ _detect_orphan_report() { echo "$nested has no root $root, so no check sees this $noun; $fix, or move it under an existing workspace" } +# Whether the CMakeLists.txt in $1 belongs to another language's build. +_cmake_owned_elsewhere() { + local dir="$1" manifest + [[ "/$dir/" != */src/* ]] || return 0 + for manifest in package.json pyproject.toml Cargo.toml go.mod build.gradle.kts Package.swift; do + [[ ! -e "$dir/$manifest" ]] || return 0 + done + return 1 +} + detect_orphan_manifests() { local lang root nested dir @@ -409,6 +423,12 @@ detect_orphan_manifests() { # without a workspace file, not a nested module missing one. [[ "$dir" != "." ]] || continue + # A CMakeLists.txt is also how other languages build native code: an + # Android NDK library under a Kotlin unit's src/, a scikit-build Python + # package, a cmake-js Node addon. Below a src/, or beside another + # language's manifest, it belongs to that build and needs no root. + if [[ "$lang" == cpp ]] && _cmake_owned_elsewhere "$dir"; then continue; fi + case "$lang" in go) _detect_orphan_report "$nested" "$root" "$noun" \ "run 'go work init ./$dir' at the repository root" ;; @@ -546,11 +566,15 @@ _capability_test_kotlin() { [[ -x ./gradlew ]] || return "$NO_RUNNER"; ./gradlew # ctest reads only the top-level CTestTestfile.cmake, which CMake writes only # when the root CMakeLists.txt calls enable_testing(). Called in a unit's alone, # every add_test() below it is skipped by that same passing message, so a -# nested test file with no top-level one is refused. +# nested test file declaring a test, with no top-level one, is refused. A +# dependency's own test files, fetched into _deps/ or built from vendor/, are +# not this project's tests: a library that calls include(CTest) regardless +# must not fail a project that has none. _capability_test_cpp() { cmake_build || return - if [[ ! -f "$CMAKE_BUILD_DIR/CTestTestfile.cmake" && - -n "$(find "$CMAKE_BUILD_DIR" -name CTestTestfile.cmake -print -quit)" ]]; then + if [[ ! -f "$CMAKE_BUILD_DIR/CTestTestfile.cmake" ]] && + find "$CMAKE_BUILD_DIR" \( -path '*/_deps' -o -path '*/vendor' \) -prune -o \ + -name CTestTestfile.cmake -exec grep -q '^add_test(' {} \; -print | grep -q .; then echo "Tests are declared below the root CMakeLists.txt, which never calls enable_testing(), so ctest finds none of them." >&2 return 1 fi diff --git a/scripts/package b/scripts/package index d0326db0..5ab85d47 100755 --- a/scripts/package +++ b/scripts/package @@ -57,10 +57,10 @@ fi # guard was written to prevent, arriving by a route it cannot see. So the # directory is emptied by the dispatch that refills it. # -# Only when a present language actually packages into it. Four of the six have -# no packaging adapter, and for a unit in one of those dist/ holds whatever its -# own build wrote -- which is what scripts/ci produces before the release walk -# reads it. Emptying that would leave the unit with less than it started with +# Only when a present language actually packages into it. Five of the seven +# have no packaging adapter, and for a unit in one of those dist/ holds +# whatever its own build wrote -- which is what scripts/ci produces before the +# release walk reads it. Emptying that would leave the unit with less than it started with # and abort the release it was meant to protect, so packaging_writes_dist is # asked first and the knowledge of which adapters write there stays beside them. # diff --git a/scripts/tests/capabilities-test b/scripts/tests/capabilities-test index 693bb9c0..2a7ea268 100755 --- a/scripts/tests/capabilities-test +++ b/scripts/tests/capabilities-test @@ -295,6 +295,23 @@ else fail "scripts/ci did not fail naming the orphaned CMakeLists.txt" fi +# A CMakeLists.txt below a src/, as an Android NDK library sits in a Kotlin +# unit, or beside another language's manifest, belongs to that build, so only +# the unit's own one is an orphan. +fixture "CMakeLists.txt owned by another build is no orphan" +mkdir -p "$work/apps/fw" "$work/apps/android/src/main/cpp" "$work/apps/ios" +printf 'add_executable(fw src/main.c)\n' > "$work/apps/fw/CMakeLists.txt" +printf 'add_library(jni SHARED jni.c)\n' > "$work/apps/android/src/main/cpp/CMakeLists.txt" +printf 'add_library(native native.c)\n' > "$work/apps/ios/CMakeLists.txt" +printf '// swift-tools-version:5.9\n' > "$work/apps/ios/Package.swift" +out="$(ci)" +if grep -q "apps/fw/CMakeLists.txt has no root" <<<"$out" && + ! grep -q "apps/android/src/main/cpp/CMakeLists.txt\|apps/ios/CMakeLists.txt" <<<"$out"; then + pass +else + fail "the orphan search did not name apps/fw's CMakeLists.txt alone: $out" +fi + # --- root manifest specificity ------------------------------------------------- # has_go accepts go.mod or go.work, and has_kotlin accepts build.gradle.kts or @@ -1314,6 +1331,35 @@ else skip "jq is not installed" fi +# CMake writes the database with the logical path it ran from, so a checkout +# reached through a symlink still lints its own units rather than none. +fixture "cpp lint matches units through a symlinked checkout" +if command -v jq >/dev/null 2>&1; then + printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeLists.txt" + mkdir -p "$work/apps/fw/src" + : > "$work/apps/fw/src/main.c" + ln -s "$work" "$work.link" + stub cmake <<'STUB' +#!/usr/bin/env bash +mkdir -p build +printf '[{"file":"%s"}]\n' "$PWD/apps/fw/src/main.c" > build/compile_commands.json +STUB + stub clang-tidy <<'STUB' +#!/usr/bin/env bash +printf '%s\n' "$@" > "${MARKER:?}" +STUB + out="$(cd "$work.link" && MARKER="$work/tidy-args" language_capabilities run lint 2>&1 /dev/null; then + pass + else + fail "clang-tidy was not handed main.c through the symlink: $out" + fi + rm -f "$work.link" +else + skip "jq is not installed" +fi + # A unit's enable_testing() without the root's leaves ctest reading no test # file and passing with "No tests were found", so the adapter refuses before # ctest runs. @@ -1322,7 +1368,7 @@ printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeList stub cmake <<'STUB' #!/usr/bin/env bash mkdir -p build/apps/fw -: > build/apps/fw/CTestTestfile.cmake +printf 'add_test([=[t]=] "/bin/true")\n' > build/apps/fw/CTestTestfile.cmake STUB stub ctest <<'STUB' #!/usr/bin/env bash @@ -1336,6 +1382,27 @@ else fail "the cpp test adapter did not refuse a nested CTestTestfile.cmake with no root one: $out" fi +# A dependency fetched into _deps/ may call include(CTest) whatever its parent +# does; its tests are not the project's, so a project with none still passes. +fixture "cpp test ignores a dependency's own tests" +printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeLists.txt" +stub cmake <<'STUB' +#!/usr/bin/env bash +mkdir -p build/_deps/dep-build build/apps/fw +printf 'add_test([=[t]=] "/bin/true")\n' > build/_deps/dep-build/CTestTestfile.cmake +printf 'subdirs("x")\n' > build/apps/fw/CTestTestfile.cmake +STUB +stub ctest <<'STUB' +#!/usr/bin/env bash +: > "${MARKER:?}" +STUB +out="$(cd "$work" && MARKER="$work/ctest-ran" language_capabilities run test 2>&1 Date: Wed, 18 Nov 2026 13:37:49 -0500 Subject: [PATCH 3/3] fix(detect): count discovered and multi-config tests in the cpp guard The narrowed enable_testing guard matched only a line starting add_test(, but gtest_discover_tests and catch_discover_tests write an include() of the discovered list in its place, and multi-config generators indent add_test() under if(CTEST_CONFIGURATION_TYPE ...). Either let a unit's tests be skipped with "No tests were found" again. The guard now matches an optionally indented add_test( or include(; a subdirs()-only file still declares nothing. Generated-By: claude-opus-5-5 --- .../src/base-repo/scripts/libs/detect.sh | 6 +++-- .../base-repo/scripts/tests/capabilities-test | 22 ++++++++++++++++++- scripts/libs/detect.sh | 6 +++-- scripts/tests/capabilities-test | 22 ++++++++++++++++++- 4 files changed, 50 insertions(+), 6 deletions(-) diff --git a/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh b/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh index 1b4296de..ed5be4c1 100644 --- a/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh +++ b/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh @@ -566,7 +566,9 @@ _capability_test_kotlin() { [[ -x ./gradlew ]] || return "$NO_RUNNER"; ./gradlew # ctest reads only the top-level CTestTestfile.cmake, which CMake writes only # when the root CMakeLists.txt calls enable_testing(). Called in a unit's alone, # every add_test() below it is skipped by that same passing message, so a -# nested test file declaring a test, with no top-level one, is refused. A +# nested test file declaring a test, with no top-level one, is refused. A test +# is an add_test(), indented under a multi-config generator, or the include() +# gtest_discover_tests and catch_discover_tests write in its place. A # dependency's own test files, fetched into _deps/ or built from vendor/, are # not this project's tests: a library that calls include(CTest) regardless # must not fail a project that has none. @@ -574,7 +576,7 @@ _capability_test_cpp() { cmake_build || return if [[ ! -f "$CMAKE_BUILD_DIR/CTestTestfile.cmake" ]] && find "$CMAKE_BUILD_DIR" \( -path '*/_deps' -o -path '*/vendor' \) -prune -o \ - -name CTestTestfile.cmake -exec grep -q '^add_test(' {} \; -print | grep -q .; then + -name CTestTestfile.cmake -exec grep -qE '^[[:space:]]*(add_test|include)\(' {} \; -print | grep -q .; then echo "Tests are declared below the root CMakeLists.txt, which never calls enable_testing(), so ctest finds none of them." >&2 return 1 fi diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test b/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test index 2a7ea268..c387b681 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test @@ -1368,7 +1368,7 @@ printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeList stub cmake <<'STUB' #!/usr/bin/env bash mkdir -p build/apps/fw -printf 'add_test([=[t]=] "/bin/true")\n' > build/apps/fw/CTestTestfile.cmake +printf 'if(CTEST_CONFIGURATION_TYPE MATCHES "^Debug$")\n add_test([=[t]=] "/bin/true")\nendif()\n' > build/apps/fw/CTestTestfile.cmake STUB stub ctest <<'STUB' #!/usr/bin/env bash @@ -1382,6 +1382,26 @@ else fail "the cpp test adapter did not refuse a nested CTestTestfile.cmake with no root one: $out" fi +# gtest_discover_tests writes an include() where add_test() would be, and a +# multi-config generator indents add_test(), so either is a declared test. +fixture "cpp test refuses discovered tests the root never enables" +printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeLists.txt" +stub cmake <<'STUB' +#!/usr/bin/env bash +mkdir -p build/apps/fw +printf 'include("/x/fw_tests_include.cmake")\n' > build/apps/fw/CTestTestfile.cmake +STUB +stub ctest <<'STUB' +#!/usr/bin/env bash +: > "${MARKER:?}" +STUB +out="$(cd "$work" && MARKER="$work/ctest-ran" language_capabilities run test 2>&1 &2 return 1 fi diff --git a/scripts/tests/capabilities-test b/scripts/tests/capabilities-test index 2a7ea268..c387b681 100755 --- a/scripts/tests/capabilities-test +++ b/scripts/tests/capabilities-test @@ -1368,7 +1368,7 @@ printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeList stub cmake <<'STUB' #!/usr/bin/env bash mkdir -p build/apps/fw -printf 'add_test([=[t]=] "/bin/true")\n' > build/apps/fw/CTestTestfile.cmake +printf 'if(CTEST_CONFIGURATION_TYPE MATCHES "^Debug$")\n add_test([=[t]=] "/bin/true")\nendif()\n' > build/apps/fw/CTestTestfile.cmake STUB stub ctest <<'STUB' #!/usr/bin/env bash @@ -1382,6 +1382,26 @@ else fail "the cpp test adapter did not refuse a nested CTestTestfile.cmake with no root one: $out" fi +# gtest_discover_tests writes an include() where add_test() would be, and a +# multi-config generator indents add_test(), so either is a declared test. +fixture "cpp test refuses discovered tests the root never enables" +printf 'cmake_minimum_required(VERSION 3.20)\nproject(p C)\n' > "$work/CMakeLists.txt" +stub cmake <<'STUB' +#!/usr/bin/env bash +mkdir -p build/apps/fw +printf 'include("/x/fw_tests_include.cmake")\n' > build/apps/fw/CTestTestfile.cmake +STUB +stub ctest <<'STUB' +#!/usr/bin/env bash +: > "${MARKER:?}" +STUB +out="$(cd "$work" && MARKER="$work/ctest-ran" language_capabilities run test 2>&1