Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .github/actions/setup-toolchains/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
6 changes: 3 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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. 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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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
4 changes: 2 additions & 2 deletions apps/github-repository-template/src/base-repo/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<unit>/` is one unit: the smallest piece delivered on its own. Its code goes in `apps/<unit>/src/`. Nothing sits directly in `apps/`.
- Split a unit into domains only for distinct business areas: `apps/<unit>/<domain>/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/`.
Expand All @@ -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. 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:

Expand Down
6 changes: 4 additions & 2 deletions apps/github-repository-template/src/base-repo/scripts/clean
Original file line number Diff line number Diff line change
Expand Up @@ -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."
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@
# The manifest filenames Dependabot reads, and the package-ecosystem each one
# earns: dependabot_ecosystem_of <basename>, 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
Expand All @@ -64,6 +64,9 @@
# nothing; Dockerfile.<anything> 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
Expand Down
Loading
Loading