Guard incomplete clangd references

scripts/dev/clangd_nav.py

@@ -324,6 +324,13 @@ def run(args: argparse.Namespace) -> int:
     compile_commands_dir = _find_compile_commands_dir(repo_root, args.compile_commands_dir)
     file_path = _resolve_file(repo_root, args.file)
 
+    if args.command == "references" and not args.background_index and not args.allow_incomplete_references:
+        raise SystemExit(
+            "references may be incomplete without clangd background indexing. "
+            "Pass --background-index for a broader best-effort query or "
+            "--allow-incomplete-references for current-translation-unit lookup."
+        )
+
     client = ClangdClient(args.clangd, compile_commands_dir, args.timeout, args.background_index)
     try:
         client.request(
@@ -391,6 +398,11 @@ def run(args: argparse.Namespace) -> int:
                 "command": command,
                 "file": str(file_path),
                 "compileCommandsDir": str(compile_commands_dir),
+                "backgroundIndex": args.background_index,
+                "referenceCompleteness": (
+                    "not-applicable" if command != "references"
+                    else ("best-effort-background-index" if args.background_index else "current-translation-unit-only")
+                ),
                 "resultCount": result_count,
                 "truncated": truncated,
                 "result": result,
@@ -424,6 +436,11 @@ def main(argv: list[str]) -> int:
         action="store_true",
         help="Allow clangd to build/use its background index for broader cross-translation-unit references.",
     )
+    parser.add_argument(
+        "--allow-incomplete-references",
+        action="store_true",
+        help="Permit current-translation-unit-only references when --background-index is not enabled.",
+    )
     parser.add_argument(
         "--hierarchical",
         action="store_true",