chore: clangd compile-db generator + upstream-sync directive

[alandtse]

What

Two developer-experience hardening changes that came out of the #135 upstream sync:

1. clangd compile database (build:)

The shipped CMake presets use the Visual Studio generator, which doesn't emit compile_commands.json (only Ninja/Makefile generators do). Without a compile DB, clangd parses every TU with the hand-maintained .clangd fallback flags and floods the editor with false "unknown include / undefined symbol" diagnostics.

tools/gen-clangd-db.ps1 stands up a throwaway Ninja configure (no build, reuses the ALL preset's installed vcpkg packages) to emit an accurate per-file DB, then drops it at the repo root where clangd auto-discovers it.

• Generalized, not machine-specific: auto-detects the MSVC dev env via vswhere, reads the vcpkg toolchain/triplet from the existing ALL cache, and builds in-place — or under a subst drive when one is mapped (MAX_PATH workaround), rewriting the emitted paths back to the real checkout.
• The generated compile_commands.json is machine-specific (absolute paths) and gitignored.
• .clangd is left intact so contributors without a generated DB keep the fallback (notably the -std=c++23 flag the DB lacks).

2. Upstream-sync directive (docs:)

New "Syncing from upstream Community Shaders" section in CLAUDE.md codifying the rule that keeps biting:

• Merge, never cherry-pick — cherry-pick rewrites SHAs so upstream commits never become ancestors and the next merge re-conflicts on the same hunks forever.
• Land the sync PR as a merge commit, never squash — squash re-collapses the ancestry, undoing the point. The repo default is squash, so it must be set explicitly.
• Includes the git merge-base --is-ancestor verification and keep-VR conflict guidance.

Release impact

None — build: tooling + docs: only. No runtime/shader code touched.

Test

• tools/gen-clangd-db.ps1 generated a 792-entry DB (787 under src/) with full per-file defines and include dirs; clangd resolves the include graph with it.
• Pre-commit hooks pass.

Summary by CodeRabbit

• Documentation

  • Added IDE/clangd setup guidance including how to generate and refresh the clangd compilation database
  • Documented upstream Community Shaders sync process, merge-based syncing guidance, verification, and conflict-resolution notes

• Chores

  • Added a PowerShell tool to generate the clangd compile_commands.json
  • Updated .gitignore to exclude the generated compilation database file

[coderabbitai]

Warning

Review limit reached

@alandtse, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 59 minutes and 59 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 73ce90a8-6ec8-428b-a97a-032c3b27bd84

📥 Commits

Reviewing files that changed from the base of the PR and between 2e37f09 and eea21a1.

📒 Files selected for processing (2)

• .claude/CLAUDE.md
• tools/gen-clangd-db.ps1

📝 Walkthrough

Walkthrough

Adds a PowerShell tool to generate a clangd compile_commands.json (handling subst drives and MSVC env), documents IDE/setup and upstream sync rules, and ignores the generated database in git.

Changes

clangd IDE integration and project tooling

Layer / File(s)	Summary
Script initialization and repository detection tools/gen-clangd-db.ps1	PowerShell script header with #requires, [CmdletBinding()], public ReuseVcpkgFrom parameter; resolves repo root via git and detects/normalizes subst drive mappings.
Build environment setup tools/gen-clangd-db.ps1	Discovers Visual Studio via vswhere, imports vcvars64.bat into the environment, validates cl on PATH, and reads CMakeCache.txt to extract CMAKE_TOOLCHAIN_FILE and VCPKG_TARGET_TRIPLET.
Compilation database generation and output tools/gen-clangd-db.ps1	Runs configure-only CMake (Ninja) with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON into build/clangd-gen, verifies compile_commands.json, rewrites subst prefixes, writes UTF-8 repo-root compile_commands.json, and reports "file" entry count.
IDE workflow and version control configuration .claude/CLAUDE.md, .gitignore	Documents clangd setup and pwsh tools/gen-clangd-db.ps1 usage, notes when to regenerate and restart clangd; adds .gitignore entry and explanatory comments for /compile_commands.json.
Upstream sync process documentation .claude/CLAUDE.md	Specifies upstream Community Shaders sync rules: use merges (no cherry-picks), land as merge commits (no squash), verify ancestry with git merge-base --is-ancestor, and resolve conflicts using --ours to preserve VR behavior.

🎯 2 (Simple) | ⏱️ ~12 minutes

🐰 A tiny script hops through drives and vars,
Rewrites paths and counts compile stars,
Docs and gitignore keep the tree neat,
clangd reads all files — oh what a treat! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately summarizes the main changes: it mentions the clangd compile-db generator and upstream-sync directive, which are the two key developer-experience improvements in this changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/clangd-compile-db

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR improves developer experience by (1) adding a PowerShell utility to generate a compile_commands.json for clangd when using Visual Studio CMake presets, and (2) documenting a repeatable upstream-sync workflow that preserves ancestry to reduce future merge conflicts.

Changes:

• Add tools/gen-clangd-db.ps1 to generate a clangd compile database via a throwaway Ninja configure using existing vcpkg artifacts.
• Gitignore the generated root-level compile_commands.json (machine-specific absolute paths).
• Extend .claude/CLAUDE.md with clangd setup instructions and explicit “merge-only” upstream sync guidance (no cherry-picks / no squash).

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 4 comments.

File	Description
tools/gen-clangd-db.ps1	New script to generate compile_commands.json by configuring with Ninja and reusing vcpkg from an existing build dir.
.gitignore	Ignore generated /compile_commands.json.
.claude/CLAUDE.md	Add clangd setup steps and codify upstream sync rules to keep merge history intact.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tools/gen-clangd-db.ps1`:
- Around line 101-104: The script hides CMake errors by piping the external
cmake invocation ("& cmake `@cmakeArgs` | Out-Null") to Out-Null; remove the "|
Out-Null" or, if you must suppress stdout, check $LASTEXITCODE immediately after
the "& cmake `@cmakeArgs`" call and throw a descriptive error that includes
CMake's exit code and any captured output; update the block around the cmake
invocation (where cmakeArgs is used) so failures are detected and reported
before the Test-Path check for $dbSrc (compile_commands.json).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 035ce9d5-992c-48bd-b898-58b6aa2f7427

📥 Commits

Reviewing files that changed from the base of the PR and between 36e8da0 and efd47d0.

📒 Files selected for processing (3)

• .claude/CLAUDE.md
• .gitignore
• tools/gen-clangd-db.ps1