Require compile context for clang-tidy

README.md

@@ -333,9 +333,11 @@ dynamically scoped `fix` and `json` behavior.
 | Systemd units | - | `systemd-analyze verify` |
 
 `clang-tidy` is intentionally gated: it runs only when the target file's parent
-chain contains `.clang-tidy`, `compile_commands.json`, or `compile_flags.txt`.
-That keeps save-time editor lint quiet for standalone C/C++ files while still
-using project-owned rule and compile metadata when it exists.
+chain contains `compile_commands.json` or `compile_flags.txt`. A nearby
+`.clang-tidy` configures rules once that compile context exists, but does not
+enable `clang-tidy` by itself. That keeps save-time editor lint quiet for
+standalone C/C++ files while still using project-owned rule and compile metadata
+when it exists.
 
 Broad project analyzers are intentionally not listed as file linters. Run them
 explicitly with `checkrun verify [PATH...]` or `--tool` filters:
@@ -351,8 +353,8 @@ explicitly with `checkrun verify [PATH...]` or `--tool` filters:
   intentional: dependency-audit results belong to locked project state, not
   standalone Rust source files.
 - Verify-time `clang-tidy` walks selected C/C++ files and directories while
-  preserving the same `.clang-tidy`, `compile_commands.json`, or
-  `compile_flags.txt` metadata gate as fast lint.
+  preserving the same `compile_commands.json` or `compile_flags.txt` metadata
+  gate as fast lint.
 - Deleted or renamed file paths are still useful verify scope hints: Go/Rust
   paths select their nearest surviving module or project, while deleted C/C++
   files select the nearest surviving non-root directory context.

lib/checkrun/linters/languages.sh

@@ -141,7 +141,9 @@ _lint_clang_tidy() {
   # The registry-level config probe is the single source of truth for whether
   # clang-tidy may run at all. Once it is allowed, discover rule config and
   # compile metadata independently because projects commonly have both and
-  # clang-tidy needs them on different CLI flags.
+  # clang-tidy needs them on different CLI flags. A .clang-tidy file configures
+  # checks, but a compile database or compile flags file is what makes the
+  # per-file invocation meaningful.
   clang_config=$(_find_config "$dir" .clang-tidy 2>/dev/null || true)
   compile_db=$(_find_config "$dir" compile_commands.json 2>/dev/null || true)
   compile_flags=$(_find_config "$dir" compile_flags.txt 2>/dev/null || true)
@@ -153,7 +155,7 @@ _lint_clang_tidy() {
     compile_root=""
   fi
 
-  [ -n "$clang_config$compile_root" ] || return 0
+  [ -n "$compile_root" ] || return 0
   [ -n "$clang_config" ] && args+=("--config-file=$clang_config")
   [ -n "$compile_root" ] && args+=("-p=$compile_root")
 

lib/checkrun/verify.py

@@ -543,7 +543,7 @@ def _clang_tidy_args(file: Path) -> list[str] | None:
     clang_config = _nearest_project_root(file, (".clang-tidy",))
     compile_db = _nearest_project_root(file, ("compile_commands.json",))
     compile_flags = _nearest_project_root(file, ("compile_flags.txt",))
-    if not clang_config and not compile_db and not compile_flags:
+    if not compile_db and not compile_flags:
         return None
 
     args = ["--quiet"]

share/checkrun/registry.json

@@ -149,11 +149,7 @@
       "fallback": { "file": "clang-format" }
     },
     "clang-tidy": {
-      "project": [
-        { "file": ".clang-tidy" },
-        { "file": "compile_commands.json" },
-        { "file": "compile_flags.txt" }
-      ],
+      "project": [{ "file": "compile_commands.json" }, { "file": "compile_flags.txt" }],
       "native": "none"
     },
     "cmake-format": {

test/suites/autolint-test

@@ -803,19 +803,34 @@ _assert_exit "cpp: clang-tidy without metadata exits 0" 0 "$rc"
 _assert_not_contains "cpp: clang-tidy without metadata is skipped" \
   "MOCK-CLANG-TIDY-ARGS:" "$output"
 
+_clang_tidy_only=$(_tmpdir)
+mkdir -p "$_clang_tidy_only/src"
+: >"$_clang_tidy_only/.clang-tidy"
+echo 'int main() { return 0; }' >"$_clang_tidy_only/src/main.cpp"
+set +e
+output=$(PATH="$_clang_tidy_mockbin:$PATH" "$AUTOLINT" "$_clang_tidy_only/src/main.cpp" 2>&1)
+rc=$?
+set -e
+_assert_exit "cpp: clang-tidy with .clang-tidy only exits 0" 0 "$rc"
+_assert_not_contains "cpp: clang-tidy with .clang-tidy only is skipped" \
+  "MOCK-CLANG-TIDY-ARGS:" "$output"
+
 _clang_with_config=$(_tmpdir)
 mkdir -p "$_clang_with_config/src"
 : >"$_clang_with_config/.clang-tidy"
+: >"$_clang_with_config/compile_commands.json"
 echo 'int main() { return 0; }' >"$_clang_with_config/src/main.cpp"
 set +e
 output=$(PATH="$_clang_tidy_mockbin:$PATH" "$AUTOLINT" "$_clang_with_config/src/main.cpp" 2>&1)
 rc=$?
 set -e
-_assert_exit "cpp: clang-tidy with .clang-tidy exits 0" 0 "$rc"
-_assert_contains "cpp: clang-tidy with .clang-tidy runs" \
+_assert_exit "cpp: clang-tidy with config and compile context exits 0" 0 "$rc"
+_assert_contains "cpp: clang-tidy with config and compile context runs" \
   "MOCK-CLANG-TIDY-ARGS:" "$output"
 _assert_contains_path_arg "cpp: clang-tidy receives --config-file" \
   "--config-file=" "$_clang_with_config/.clang-tidy" "$output"
+_assert_contains_path_arg "cpp: clang-tidy receives -p compile context root" \
+  "-p=" "$_clang_with_config" "$output"
 
 _clang_with_db=$(_tmpdir)
 mkdir -p "$_clang_with_db/src"
@@ -2747,6 +2762,7 @@ EOF
 chmod +x "$_json_clang_mock/clang-tidy"
 _json_clang_dir=$(_tmpdir)
 : >"$_json_clang_dir/.clang-tidy"
+: >"$_json_clang_dir/compile_commands.json"
 cat >"$_json_clang_dir/main.cpp" <<'EOF'
 int main() {
   return 0;

test/suites/registry-test

@@ -203,12 +203,11 @@ for relative, (expected_format, expected_lint) in matrix.items():
     assert [step["adapter"] for step in format_steps] == expected_format, relative
     assert [step["adapter"] for step in lint_steps] == expected_lint, relative
 
-clang_config_payloads = {
-    ".clang-tidy": "Checks: '*'\n",
+clang_context_payloads = {
     "compile_commands.json": "[]\n",
     "compile_flags.txt": "-std=c++20\n",
 }
-for config_name, config_payload in clang_config_payloads.items():
+for config_name, config_payload in clang_context_payloads.items():
     c_with_config = (
         tmp / f"with-clang-config-{config_name.replace('.', '_')}" / "src" / "main.cpp"
     )
@@ -230,6 +229,49 @@ for config_name, config_payload in clang_config_payloads.items():
     assert clang_step["config"]["source"] == "project"
     assert clang_step["config"]["path"].endswith(config_name)
 
+c_with_tidy_only = tmp / "with-clang-tidy-only" / "src" / "main.cpp"
+c_with_tidy_only.parent.mkdir(parents=True, exist_ok=True)
+(c_with_tidy_only.parent.parent / ".clang-tidy").write_text(
+    "Checks: '*'\n", encoding="utf-8"
+)
+c_with_tidy_only.write_text("", encoding="utf-8")
+c_with_tidy_only_plan = registry_mod.plan(registry, [str(c_with_tidy_only)], "lint")[
+    "files"
+][0]["lint"]
+assert [step["adapter"] for step in c_with_tidy_only_plan["steps"]] == [
+    "typos",
+    "schema-lint",
+]
+clang_tidy_only_skips = [
+    step for step in c_with_tidy_only_plan["skipped"] if step["adapter"] == "clang-tidy"
+]
+assert len(clang_tidy_only_skips) == 1
+assert clang_tidy_only_skips[0]["requiresConfigMatch"] is True
+assert clang_tidy_only_skips[0]["reason"] == "missing-config"
+assert clang_tidy_only_skips[0]["config"]["source"] == "none"
+
+c_with_config_and_context = tmp / "with-clang-config-and-context" / "src" / "main.cpp"
+c_with_config_and_context.parent.mkdir(parents=True, exist_ok=True)
+(c_with_config_and_context.parent.parent / ".clang-tidy").write_text(
+    "Checks: '*'\n", encoding="utf-8"
+)
+(c_with_config_and_context.parent.parent / "compile_commands.json").write_text(
+    "[]\n", encoding="utf-8"
+)
+c_with_config_and_context.write_text("", encoding="utf-8")
+c_with_config_and_context_plan = registry_mod.plan(
+    registry, [str(c_with_config_and_context)], "lint"
+)["files"][0]["lint"]
+assert [step["adapter"] for step in c_with_config_and_context_plan["steps"]] == [
+    "typos",
+    "schema-lint",
+    "clang-tidy",
+]
+clang_step = c_with_config_and_context_plan["steps"][-1]
+assert clang_step["requiresConfigMatch"] is True
+assert clang_step["config"]["source"] == "project"
+assert clang_step["config"]["path"].endswith("compile_commands.json")
+
 c_without_config = tmp / "without-clang-config" / "main.cpp"
 c_without_config.parent.mkdir(parents=True, exist_ok=True)
 c_without_config.write_text("", encoding="utf-8")

test/suites/verify-test

@@ -106,6 +106,7 @@ EOF
 cat >"$_default_root/cpp/.clang-tidy" <<'EOF'
 Checks: '-*,bugprone-*'
 EOF
+: >"$_default_root/cpp/compile_commands.json"
 cat >"$_default_root/cpp/src/main.cpp" <<'EOF'
 int main() { return 0; }
 EOF
@@ -432,15 +433,21 @@ _assert_eq "cargo-clippy: deleted non-rust path is not a project scope hint" ""
 echo "=== checkrun: clang-tidy file discovery ==="
 
 _cpp_root=$(_realpath_dir "$(_tmpdir)")
+_cpp_tidy_only_root=$(_realpath_dir "$(_tmpdir)")
 _cpp_unconfigured_root=$(_realpath_dir "$(_tmpdir)")
-mkdir -p "$_cpp_root/src" "$_cpp_root/include" "$_cpp_unconfigured_root"
+mkdir -p "$_cpp_root/src" "$_cpp_root/include" "$_cpp_tidy_only_root" "$_cpp_unconfigured_root"
 : >"$_cpp_root/.clang-tidy"
+: >"$_cpp_root/compile_commands.json"
 cat >"$_cpp_root/src/main.cpp" <<'EOF'
 int main() { return 0; }
 EOF
 cat >"$_cpp_root/include/demo.hpp" <<'EOF'
 int demo();
 EOF
+cat >"$_cpp_tidy_only_root/tidy-only.cpp" <<'EOF'
+int tidy_only();
+EOF
+: >"$_cpp_tidy_only_root/.clang-tidy"
 cat >"$_cpp_unconfigured_root/no-config.cpp" <<'EOF'
 int no_config();
 EOF
@@ -461,16 +468,19 @@ CLANG_TIDY_LOG="$_clang_tidy_log" PATH="$_clang_tidy_mock:$PATH" \
   "$_cpp_root/src/main.cpp" \
   "$_cpp_root/src/main.cpp" \
   "$_cpp_root/include" \
+  "$_cpp_tidy_only_root/tidy-only.cpp" \
   "$_cpp_unconfigured_root/no-config.cpp" >/dev/null 2>&1
 rc=$?
 set -e
 _assert_exit "clang-tidy: exits 0 for clean files" 0 "$rc"
 _clang_tidy_call_count=$(wc -l <"$_clang_tidy_log" | tr -d ' ')
 _assert_eq "clang-tidy: deduplicates repeated files" "2" "$_clang_tidy_call_count"
 _assert_contains "clang-tidy: runs selected source file with project config" \
-  "--quiet --config-file=$_cpp_root/.clang-tidy $_cpp_root/src/main.cpp" "$(cat "$_clang_tidy_log")"
+  "--quiet --config-file=$_cpp_root/.clang-tidy -p=$_cpp_root $_cpp_root/src/main.cpp" "$(cat "$_clang_tidy_log")"
 _assert_contains "clang-tidy: walks selected directories for C++ headers" \
-  "--quiet --config-file=$_cpp_root/.clang-tidy $_cpp_root/include/demo.hpp" "$(cat "$_clang_tidy_log")"
+  "--quiet --config-file=$_cpp_root/.clang-tidy -p=$_cpp_root $_cpp_root/include/demo.hpp" "$(cat "$_clang_tidy_log")"
+_assert_not_contains "clang-tidy: .clang-tidy without compile context is skipped" \
+  "$_cpp_tidy_only_root/tidy-only.cpp" "$(cat "$_clang_tidy_log")"
 _assert_not_contains "clang-tidy: skips C++ files without metadata gate" \
   "$_cpp_unconfigured_root/no-config.cpp" "$(cat "$_clang_tidy_log")"
 
@@ -482,7 +492,7 @@ rc=$?
 set -e
 _assert_exit "clang-tidy: deleted file scope exits 0" 0 "$rc"
 _assert_contains "clang-tidy: deleted file scopes to surviving directory context" \
-  "--quiet --config-file=$_cpp_root/.clang-tidy $_cpp_root/src/main.cpp" "$(cat "$_clang_tidy_log")"
+  "--quiet --config-file=$_cpp_root/.clang-tidy -p=$_cpp_root $_cpp_root/src/main.cpp" "$(cat "$_clang_tidy_log")"
 _assert_not_contains "clang-tidy: deleted file does not lint missing path" \
   "$_cpp_root/src/deleted.cpp" "$(cat "$_clang_tidy_log")"
 
@@ -494,7 +504,7 @@ rc=$?
 set -e
 _assert_exit "clang-tidy: deleted parent scope exits 0" 0 "$rc"
 _assert_contains "clang-tidy: deleted parent scopes to surviving directory context" \
-  "--quiet --config-file=$_cpp_root/.clang-tidy $_cpp_root/src/main.cpp" "$(cat "$_clang_tidy_log")"
+  "--quiet --config-file=$_cpp_root/.clang-tidy -p=$_cpp_root $_cpp_root/src/main.cpp" "$(cat "$_clang_tidy_log")"
 _assert_not_contains "clang-tidy: deleted parent does not lint missing path" \
   "$_cpp_root/src/removed/deleted.cpp" "$(cat "$_clang_tidy_log")"