From 435afba5658b7bc08bc8e32ff8c468372177b4dd Mon Sep 17 00:00:00 2001 From: Alan George Date: Wed, 10 Jun 2026 10:57:25 -0600 Subject: [PATCH 1/2] AGENTS, readme, script cleanup --- AGENTS.md | 49 ++++++++++++++++++++++++++-- docs/tools.md | 9 ++--- scripts/clang-tidy.sh | 76 ++++++++++++++++++++++++------------------- 3 files changed, 94 insertions(+), 40 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 64107fd0..77f6467f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -326,11 +326,54 @@ malformed table, missing `@param` on a documented function, …) fails the build Code should be easy to read and understand. If a sacrifice is made for performance or readability, it should be documented. -Adhere to clang-format checks configured in `.clang-format`. Run `./scripts/clang-format.sh` if needed to confirm code styling, and `./scripts/clang-format.sh --fix` to auto-format generated code created. +#### Formatting (clang-format) -### Static Analysis +The repo enforces `.clang-format` in CI (see `.github/workflows/builds.yml` → +`clang-format` job). Any divergence fails the build. -Adhere to clang-tidy checks configured in `.clang-tidy`. Run `./scripts/clang-tidy.sh` if needed to confirm code quality. +**Required workflow when generating or editing C/C++ code:** + +1. After completing a set of edits to any `.c`, `.cc`, `.cpp`, `.cxx`, `.h`, + `.hpp`, or `.hxx` file under `src/`, `include/`, or `benchmarks/`, run: + + ```bash + ./scripts/clang-format.sh --fix + ``` + + Pass the explicit paths so the run is fast; omit them only when doing a + sweep over the entire tree. +2. If clang-format reports any rewrites, treat the rewritten contents as the + final state and re-read the file before doing any further edits to it. +3. Do not commit, hand off, or declare a task complete with un-formatted + code. CI will reject it and the round-trip wastes time. + +`./scripts/clang-format.sh` (no `--fix`) runs in dry-run / `--Werror` mode and +is what CI uses; it exits non-zero on any divergence. + +#### Static Analysis (clang-tidy) + +The repo enforces `.clang-tidy` in CI (see `.github/workflows/builds.yml` → +`clang-tidy` job, run with `--fail-on-warning`). Any new warning fails the +build. + +**Required workflow when generating or editing C/C++ code:** + +1. After substantive C/C++ edits — especially anything that adds new + identifiers, new enums, new public API, new free functions, or that + touches the FFI / threading boundary — run: + + ```bash + ./scripts/clang-tidy.sh + ``` + + This requires a prior `./build.sh release` (or + `./build.sh release-tests` / `release-all`) so that + `build-release/compile_commands.json` and the generated protobuf headers + exist. +2. Address any new findings introduced by your edits. Do not introduce new + `// NOLINT` suppressions without a one-line comment explaining *why*. +3. Pre-existing findings in code you did not touch are out of scope unless + the user explicitly asks for a sweep. ## Dependencies diff --git a/docs/tools.md b/docs/tools.md index b67826f5..c8be00ac 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -49,12 +49,13 @@ sudo apt-get install clang-format clang-tidy clang-tools ./scripts/clang-tidy.sh ``` -The wrapper forwards extra arguments to `run-clang-tidy`: +With no arguments, runs against every relevant file in the repository against +the checks in `.clang-tidy`. ```bash -./scripts/clang-tidy.sh -j 4 # Number of cores -./scripts/clang-tidy.sh -checks='-*,misc-const-correctness' # Only specific checks -./scripts/clang-tidy.sh -fix # Apply fixes +./scripts/clang-tidy.sh src/ffi_client.cpp # Check just this file +./scripts/clang-tidy.sh -j 4 # Override worker count +./scripts/clang-tidy.sh --fix # Apply fixes ``` Output is captured to `clang-tidy.log` at the repo root, since the terminal diff --git a/scripts/clang-tidy.sh b/scripts/clang-tidy.sh index 9ff1d67e..596b63ed 100755 --- a/scripts/clang-tidy.sh +++ b/scripts/clang-tidy.sh @@ -61,7 +61,7 @@ cd "${script_dir}/.." # users who hit a pre-flight error or a bad argument get pointed at this. usage() { cat <<'EOF' -Usage: ./scripts/clang-tidy.sh [OPTIONS] [FILE...] [run-clang-tidy args...] +Usage: ./scripts/clang-tidy.sh [OPTIONS] [FILE...] Run clang-tidy locally or in CI using the same file set and config that the repo's CI workflow uses. Picks up checks from the repo-root .clang-tidy. @@ -70,7 +70,7 @@ Options: -h, --help, -? Show this help and exit. --fix - Apply fixes in place (forwarded to run-clang-tidy as -fix). + Apply fixes in place. --github-actions, --gh Force GitHub Actions annotation + step-summary mode. Auto-detected when GITHUB_ACTIONS=true. @@ -78,6 +78,8 @@ Options: Exit non-zero when any warning is emitted (errors already exit non-zero on their own). Off by default for local edit/run cycles; CI opts in via the workflow file. + -j N + Override the clang-tidy worker count. Defaults to nproc / hw.ncpu. Positional arguments: FILE... @@ -86,10 +88,6 @@ Positional arguments: to scope the run to a single file or a curated set, e.g.: ./scripts/clang-tidy.sh -Any other arguments are forwarded verbatim to run-clang-tidy. Common ones: - -j N worker count (defaults to nproc / sysctl hw.ncpu) - -checks=... override the .clang-tidy check list for this run - Examples: ./scripts/clang-tidy.sh # full src/ tree ./scripts/clang-tidy.sh # single file @@ -135,8 +133,8 @@ fi # not just on errors. Off by default so local edit/run cycles aren't blocked # by in-progress code; CI opts in via the workflow file. FAIL_ON_WARNING=0 +FIX_MODE=0 -forward_args=() explicit_files=() while (($#)); do case "$1" in @@ -146,10 +144,7 @@ while (($#)); do exit 0 ;; --fix) - # Unify with clang-format.sh's --fix spelling. run-clang-tidy only - # understands the single-dash -fix, so normalize every accepted form - # to that when forwarding. - forward_args+=("-fix") + FIX_MODE=1 shift ;; --github-actions|--gh) @@ -160,37 +155,45 @@ while (($#)); do FAIL_ON_WARNING=1 shift ;; + -j) + if [[ $# -lt 2 || ! "$2" =~ ^[1-9][0-9]*$ ]]; then + echo "ERROR: -j requires a positive integer worker count." >&2 + usage >&2 + exit 2 + fi + jobs="$2" + shift 2 + ;; --) - # Explicit forwarding separator: everything after `--` goes straight - # to run-clang-tidy without further interpretation. + # Explicit positional separator: everything after `--` is a file path. shift - forward_args+=("$@") + explicit_files+=("$@") break ;; - --*) - # Long options we don't recognize are user typos far more often than - # genuine run-clang-tidy long options (run-clang-tidy uses single-dash - # long options like -fix, -j, -checks=...). Reject and surface usage. + --*|-*) echo "ERROR: unknown option: $1" >&2 usage >&2 exit 2 ;; *) - # A positional arg naming an existing file is an explicit target to - # analyze; anything else (e.g. the value after -j, a -checks=... flag) - # is forwarded verbatim to run-clang-tidy. When explicit files are - # given they replace the default src/ FILE_REGEX below so the run is - # scoped to exactly those files. - if [[ -f "$1" ]]; then - explicit_files+=("$1") - else - forward_args+=("$1") - fi + explicit_files+=("$1") shift ;; esac done +for path in "${explicit_files[@]}"; do + if [[ -f "${path}" ]]; then + continue + fi + if [[ -e "${path}" ]]; then + echo "ERROR: clang-tidy target is not a regular file: ${path}" >&2 + else + echo "ERROR: clang-tidy target does not exist: ${path}" >&2 + fi + exit 2 +done + if [[ ! -f "${BUILD_DIR}/compile_commands.json" ]]; then echo "ERROR: ${BUILD_DIR}/compile_commands.json not found." >&2 echo "Run: ./build.sh release (configures + builds, generates protobuf headers)" >&2 @@ -248,10 +251,17 @@ fi # coreutils tool; macOS doesn't ship it, so fall back to `sysctl hw.ncpu`, # and finally to a conservative 4 if neither is available (e.g. a minimal # container). -if command -v nproc >/dev/null 2>&1; then - jobs=$(nproc) -else - jobs=$(sysctl -n hw.ncpu 2>/dev/null || echo 4) +if [[ -z "${jobs:-}" ]]; then + if command -v nproc >/dev/null 2>&1; then + jobs=$(nproc) + else + jobs=$(sysctl -n hw.ncpu 2>/dev/null || echo 4) + fi +fi + +tidy_args=() +if (( FIX_MODE == 1 )); then + tidy_args+=("-fix") fi # -------- Begin GitHub Actions annotations -------- @@ -536,7 +546,7 @@ PYTHONUNBUFFERED=1 run-clang-tidy \ -quiet \ -j "${jobs}" \ ${extra_args[@]+"${extra_args[@]}"} \ - ${forward_args[@]+"${forward_args[@]}"} \ + ${tidy_args[@]+"${tidy_args[@]}"} \ "${tidy_targets[@]}" \ 2>&1 | tee "${log}" rc="${PIPESTATUS[0]}" From c0207ebd6f9e049924cb58f3f32e7f095a0a83c6 Mon Sep 17 00:00:00 2001 From: Alan George Date: Wed, 10 Jun 2026 17:33:43 -0600 Subject: [PATCH 2/2] Cleanup agents --- AGENTS.md | 49 +++---------------------------------------------- 1 file changed, 3 insertions(+), 46 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 77f6467f..9bf3afd7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -326,54 +326,11 @@ malformed table, missing `@param` on a documented function, …) fails the build Code should be easy to read and understand. If a sacrifice is made for performance or readability, it should be documented. -#### Formatting (clang-format) +Adhere to clang-format checks configured in `.clang-format`. After C++ code changes, run `./scripts/clang-format.sh` to confirm styling, or `./scripts/clang-format.sh --fix` to auto-format. -The repo enforces `.clang-format` in CI (see `.github/workflows/builds.yml` → -`clang-format` job). Any divergence fails the build. +### Static Analysis -**Required workflow when generating or editing C/C++ code:** - -1. After completing a set of edits to any `.c`, `.cc`, `.cpp`, `.cxx`, `.h`, - `.hpp`, or `.hxx` file under `src/`, `include/`, or `benchmarks/`, run: - - ```bash - ./scripts/clang-format.sh --fix - ``` - - Pass the explicit paths so the run is fast; omit them only when doing a - sweep over the entire tree. -2. If clang-format reports any rewrites, treat the rewritten contents as the - final state and re-read the file before doing any further edits to it. -3. Do not commit, hand off, or declare a task complete with un-formatted - code. CI will reject it and the round-trip wastes time. - -`./scripts/clang-format.sh` (no `--fix`) runs in dry-run / `--Werror` mode and -is what CI uses; it exits non-zero on any divergence. - -#### Static Analysis (clang-tidy) - -The repo enforces `.clang-tidy` in CI (see `.github/workflows/builds.yml` → -`clang-tidy` job, run with `--fail-on-warning`). Any new warning fails the -build. - -**Required workflow when generating or editing C/C++ code:** - -1. After substantive C/C++ edits — especially anything that adds new - identifiers, new enums, new public API, new free functions, or that - touches the FFI / threading boundary — run: - - ```bash - ./scripts/clang-tidy.sh - ``` - - This requires a prior `./build.sh release` (or - `./build.sh release-tests` / `release-all`) so that - `build-release/compile_commands.json` and the generated protobuf headers - exist. -2. Address any new findings introduced by your edits. Do not introduce new - `// NOLINT` suppressions without a one-line comment explaining *why*. -3. Pre-existing findings in code you did not touch are out of scope unless - the user explicitly asks for a sweep. +Adhere to clang-tidy checks configured in `.clang-tidy`. After C++ code changes, run `./scripts/clang-tidy.sh` to confirm code quality. ## Dependencies