If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/rizsotto/Bear shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 4d ago
• 5 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 95% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live rizsotto/Bear repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rizsotto/Bear.

What it runs against: a local clone of rizsotto/Bear — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in rizsotto/Bear | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rizsotto/Bear. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rizsotto/Bear.git
#   cd Bear
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of rizsotto/Bear and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "rizsotto/Bear(\\.git)?\\b" \\
  && ok "origin remote is rizsotto/Bear" \\
  || miss "origin remote is not rizsotto/Bear (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "bear/src/bin/driver.rs" \\
  && ok "bear/src/bin/driver.rs" \\
  || miss "missing critical file: bear/src/bin/driver.rs"
test -f "bear/src/intercept/mod.rs" \\
  && ok "bear/src/intercept/mod.rs" \\
  || miss "missing critical file: bear/src/intercept/mod.rs"
test -f "bear-codegen/src/lib.rs" \\
  && ok "bear-codegen/src/lib.rs" \\
  || miss "missing critical file: bear-codegen/src/lib.rs"
test -f "bear/src/output/clang/converter.rs" \\
  && ok "bear/src/output/clang/converter.rs" \\
  || miss "missing critical file: bear/src/output/clang/converter.rs"
test -f "bear/src/config/mod.rs" \\
  && ok "bear/src/config/mod.rs" \\
  || miss "missing critical file: bear/src/config/mod.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/rizsotto/Bear"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Bear is a build system agnostic tool that generates JSON compilation databases for clang tooling by intercepting compiler invocations at build time. It captures gcc, clang, msvc, and 10+ other compiler calls across Linux, macOS, BSD, and Windows, producing a compile_commands.json file that tools like clangd, clang-tidy, and clang-format can consume to understand project structure without native build system support. Rust workspace monorepo with 6 members: (1) bear — main CLI binary using clap 4.5 for argument parsing; (2) bear-codegen — compiler flag pattern recognition and YAML-driven code generation targeting gcc, clang, msvc, cuda, flang, etc.; (3) intercept-preload — LD_PRELOAD / system-level compiler call interception layer; (4) bear-completions — shell completion generation; (5) platform-checks — cross-platform capability probing; (6) integration-tests — end-to-end test suite.

C/C++ developers and teams using build systems (Make, Autotools, custom scripts) that don't natively emit JSON compilation databases; also IDE/language-server maintainers integrating with non-CMake/Meson/Bazel projects who need reliable compiler metadata.

Production-ready. The project is at v4.1.3 with GPL-3.0-or-later licensing, has comprehensive CI via GitHub Actions (build_rust.yml), snapshot tests for 13+ compiler variants (gcc, clang, msvc, cuda, etc.), and active maintenance visible in the workspace structure. The codebase is Rust-first (969KB) with C interop layers, indicating deliberate engineering for systems-level reliability.

Standard open source risks apply.

Active maintenance on compiler variant coverage and code generation. The bear-codegen module contains 13 snapshot tests (armclang, clang, gcc, msvc, cuda, flang, intel, nvidia-hpc, ibm-xl, cray-fortran, etc.) and proptest property-based tests, indicating recent work on pattern matching robustness. Edition bumped to '2024' in Cargo.toml suggests recent MSRV updates.

git clone https://github.com/rizsotto/Bear.git
cd Bear
cargo build --release
./target/release/bear -- make  # or your build command
cat compile_commands.json

Daily commands:

cargo build --release
cargo test  # runs unit + integration tests, snapshot tests via insta
./target/release/bear -- <your-build-command>

• bear/src/bin/driver.rs — Main entry point for the Bear tool that orchestrates compilation database generation and must be understood to grasp the overall execution flow.
• bear/src/intercept/mod.rs — Core interception mechanism that captures compiler invocations during build—the heart of Bear's functionality and essential for understanding how it works.
• bear-codegen/src/lib.rs — Code generation library that parses compiler YAML specifications and generates flag recognition tables—critical for supporting multiple compiler toolchains.
• bear/src/output/clang/converter.rs — Converts intercepted build commands into the standardized JSON compilation database format that tools depend on.
• bear/src/config/mod.rs — Configuration system that loads and validates user settings—required for customizing Bear's behavior across different build environments.
• Cargo.toml — Workspace manifest defining all crate dependencies and versions; must be reviewed when troubleshooting build or dependency issues.
• bear/interpreters/gcc.yaml — Example compiler specification file that defines how GCC flags are recognized—foundational pattern for adding support for new compilers.

Add Support for a New Compiler

1. Create a new YAML file in bear/interpreters/ following the GCC/Clang pattern (e.g., bear/interpreters/mycompiler.yaml) that defines how to recognize flags, language standards, and output files (bear/interpreters/gcc.yaml)
2. Add the YAML specification to bear/build.rs so it gets embedded into the binary during compilation (bear/build.rs)
3. Add unit tests in bear-codegen/tests/snapshots.rs with a new snapshot file to validate flag recognition for your compiler (bear-codegen/tests/snapshots.rs)
4. Verify the compiler spec by running snapshot tests: cargo test --package bear-codegen, then update snapshots if needed (bear-codegen/tests/snapshots)

Modify Compilation Database Output Format

1. Edit bear/src/output/clang/json.rs to change JSON serialization logic for compilation database entries (bear/src/output/clang/json.rs)
2. Update the converter logic in bear/src/output/clang/converter.rs to transform intercepted events into the new format (bear/src/output/clang/converter.rs)
3. Add new output format type to bear/src/output/formats.rs if introducing a format variant (bear/src/output/formats.rs)

Add a New Configuration Option

1. Define the new configuration field in bear/src/config/types.rs as a struct member (bear/src/config/types.rs)
2. Add validation logic for the new option in bear/src/config/validation.rs (bear/src/config/validation.rs)
3. Update the configuration loader in bear/src/config/loader.rs to parse the new option from config files or environment (bear/src/config/loader.rs)
4. Thread the configuration through bear/src/context.rs to make it available at runtime (bear/src/context.rs)

Enhance Compiler Invocation Interception

1. Modify the interception logic in bear/src/intercept/mod.rs to capture additional compiler metadata or environment variables (bear/src/intercept/mod.rs)
2. Update the reporter in bear/src/intercept/reporter.rs to aggregate and emit new fields in compilation events (bear/src/intercept/reporter.rs)
3. Adjust the TCP protocol in bear/src/intercept/tcp.rs if new data types need to be serialized between wrapper and driver (bear/src/intercept/tcp.rs)

• Rust — Provides memory safety without GC, essential for a low-overhead build intercept tool that must be performant and reliable across POSIX and Windows platforms.
• LD_PRELOAD / process supervision — Intercepts compiler invocations at the OS level without requiring build system modifications, allowing Bear to work with any build system (Make, CMake, Bazel, etc.).
• YAML compiler specifications — Declarative, maintainable format for defining compiler-specific flag recognition patterns, making it easy to add support for new compilers without recompiling.
• Code generation (bear-codegen) — Pre-compiles YAML specs into Rust lookup tables at build time, avoiding runtime parsing overhead and ensuring fast flag recognition during interception.

• Embedding compiler specs at compile time via build.rs rather than loading from disk at runtime

  • Why: Simplifies deployment (no external files) and ensures specs match the binary version, but requires rebuild to update compiler support.
  • Consequence: Users cannot easily customize compiler specs without recompiling; trade-off favors simplicity and correctness over flexibility.

• Process-level interception via LD_PRELOAD instead of modifying build files or using strace/ptrace

  • Why: Minimal overhead, no build system changes, works transparently with any build system.
  • Consequence: Requires shell environment injection; may miss compilers invoked directly from non-shell contexts; less portable to Windows (though there is Windows support via different mechanisms).

• TCP-based communication between wrapper processes and the driver

  • Why: Allows scalable asynchronous collection of events from parallel compiler invocations without blocking.
  • Consequence: Adds networking overhead; requires port availability; slightly more complex error handling than file-based IPC.

• Does not directly integrate with IDEs; produces a compilation database that IDEs consume via their Clang tooling support.
• Does not modify or cache build artifacts; only generates metadata about how compilation occurred.
• Does not provide real-time build monitoring or visualization; produces a static database after the build completes.
• Does not support compilers without YAML specifications in the interpreters directory.

No false negatives from SIP/sandboxing: On macOS with System Integrity Protection, LD_PRELOAD is stripped from system binaries; the wiki documents workarounds (code signing, entitlements). YAML-to-Rust codegen coupling: Changes to compiler flag tables in YAML require re-running codegen to regenerate Rust source; missing this step causes stale compiler variant support. Cross-platform libc differences: errno and signal-hook usage differs between glibc/musl/BSD; platform-checks crate probes these at compile time (check build.rs). Edition 2024 requires Rust 1.85+: Verify MSRV in CI if upgrading dependencies. Environment injection race: bear sets LD_PRELOAD before executing child build; if build changes env or forks with exec, interception may fail silently—integration tests validate this.

• JSON Compilation Database (JSONCDB) — The core data format Bear emits; understanding the schema (file, directory, command, arguments) is essential to diagnosing why clang tools do or don't work with captured builds.
• LD_PRELOAD / Function Interposition — Bear's Unix implementation hooks libc exec*/fork/execve calls via LD_PRELOAD to capture compiler invocations; understanding this is critical for debugging macOS SIP issues and platform-specific failures.
• Compiler Flag Parsing via Regular Expressions — bear-codegen/src/recognition.rs uses regex-lite to parse compiler command lines into flag semantics (include paths, optimization levels, defines); extending it for new compilers requires regex pattern design.
• YAML-Driven Code Generation — bear-codegen generates Rust flag parsers from YAML tables (bear-codegen/src/yaml_types.rs); changes to compiler tables trigger codegen, avoiding manual Rust duplication for each of 13+ compiler variants.
• Snapshot Testing (Insta) — bear-codegen/tests/snapshots.rs uses insta crate to validate codegen output for all compiler variants; modifying codegen requires reviewing and approving snapshot diffs, preventing silent regressions.
• Process Interception and Signal Handling — Bear spawns child builds as subprocesses and captures their compiler calls via signal-hook and crossbeam-channel; understanding SIGCHLD, exit code forwarding, and multi-threaded signal safety is key to reliability.
• Cross-Platform Libc Abstraction — bear uses libc and errno crates to abstract glibc/musl/BSD differences in syscalls and error handling; platform-checks crate probes compile-time capabilities to ensure correct interception on each OS.

• cmake/cmake — CMake natively exports compile_commands.json via CMAKE_EXPORT_COMPILE_COMMANDS=ON; use Bear only if CMake isn't available.
• mesonbuild/meson — Meson also generates compile_commands.json natively; Bear is for legacy build systems (Autotools, Make, hand-rolled scripts) that Meson doesn't support.
• clangd/clangd — clangd language server consumes compile_commands.json to provide IDE features; Bear is the bridge for projects without native DB export.
• nix-community/nix — Nix sandboxing breaks LD_PRELOAD interception; the Bear wiki documents Nix-specific workarounds and shell.nix integration patterns.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for compiler interpreter YAML validation

The repo has 13 compiler interpreter YAML files (gcc.yaml, clang.yaml, msvc.yaml, etc.) in bear/interpreters/ but the existing bear-codegen/tests/yaml_validation.rs appears minimal. New contributors could add comprehensive tests to validate: (1) all interpreter YAML files parse correctly, (2) required fields are present in each interpreter definition, (3) flag patterns don't conflict across interpreters, and (4) environment variable substitutions work correctly. This directly improves the robustness of the core feature.

• [ ] Extend bear-codegen/tests/yaml_validation.rs to load all YAML files from bear/interpreters/
• [ ] Add schema validation tests for required fields in interpreter definitions (name, patterns, flags, etc.)
• [ ] Add cross-interpreter validation to detect conflicting flag patterns
• [ ] Add test cases for environment variable resolution against each interpreter file using bear-codegen/src/env_keys.rs logic

Add missing snapshot tests for edge-case compiler flag combinations

The bear-codegen/tests/snapshots/ directory has snapshots for 13 compilers but lacks tests for realistic edge cases: (1) mixed flags (optimization + debugging + warnings), (2) compiler-specific flag variations (-Ofast vs -O3), (3) unsupported/unrecognized flags handling, and (4) flag ordering impact. These snapshots help catch regressions when bear-codegen/src/recognition.rs or flag parsing logic changes.

• [ ] Review bear-codegen/src/recognition.rs to identify untested flag combination patterns
• [ ] Create new snapshot test file bear-codegen/tests/snapshots.rs with test cases for mixed compiler flags
• [ ] Add snapshot test case for conflicting or redundant flags (e.g., -O2 and -O3 together)
• [ ] Run insta snapshot tests to generate baseline snapshots for future regression detection

Add platform-specific shell completion tests for bear-completions

The bear-completions module generates shell completions via bear-completions/src/bin/generate_completions.rs but integration-tests likely doesn't validate that generated completions actually work in bash/zsh/fish. New contributors could add tests that: (1) generate completions, (2) verify syntax validity for each shell, (3) test actual completion triggers (e.g., 'bear --' produces correct suggestions). This ensures users get working completions across platforms.

• [ ] Add test in integration-tests/ that calls generate_completions and validates output format for bash, zsh, fish
• [ ] Add shell syntax validation tests (bash -n for bash completions, etc.)
• [ ] Add tests that source the generated completion files and verify completion functions are defined
• [ ] Reference the output against clap_complete's expected behavior for each shell type

• Add snapshot tests for Fortran compiler variants (flang, intel-fortran, cray-fortran snapshots exist but coverage gaps remain): extend bear-codegen/tests/snapshots.rs to test -Bstatic/-Bdynamic flag variations not yet validated in flang snapshots.
• Document environment variable keys generated by bear-codegen in a generated Markdown file: the bear-codegen/src/env_keys.rs module defines LD_PRELOAD variable names and injection strategy, but there's no human-readable reference in INSTALL.md or README—add a doc table showing which env vars are set on each platform.
• Add proptest property-based tests for Windows MSVC flag parsing: bear-codegen/tests/proptest_patterns.rs exists but has limited MSVC coverage; add property generators for MSVC-specific flags like /Wall, /Werror, /permissive- to catch undiscovered edge cases in recognition.rs.

The Bear codebase demonstrates generally good security practices with use of Rust's memory safety features and reasonable dependency management. However, there is a critical configuration issue with the Rust edition specification that will prevent compilation. Secondary concerns include the use of early-stage YAML parsing libraries, shell command processing that requires careful input validation, and process interception mechanisms that should be carefully audited. Regular dependency audits using 'cargo audit' and security code review of the intercept modules are recommended. No hardcoded secrets, SQL injection risks, or XSS vulnerabilities were identified in the provided file structure.

• Medium · Rust Edition 2024 Not Yet Released — Cargo.toml - [workspace.package] edition field. The Cargo.toml specifies edition = '2024', which is not an official Rust edition as of the knowledge cutoff. Valid editions are 2015, 2018, and 2021. This will cause compilation failures and indicates potential misconfiguration or a typo in the workspace configuration. Fix: Change edition to '2021' (the latest stable edition) or '2018' depending on the minimum supported Rust version. Verify the intended Rust edition and update accordingly.
• Low · Dependency on serde-saphyr with Limited Maintenance — Cargo.toml - workspace.dependencies - serde-saphyr. The dependency 'serde-saphyr' version 0.0.24 appears to be from an early development stage (0.0.x versioning). Limited maintenance status could lead to unpatched security vulnerabilities in YAML parsing functionality. Fix: Monitor the serde-saphyr repository for security updates. Consider switching to more actively maintained YAML parsing libraries if security issues are discovered. Regularly audit dependencies using 'cargo audit'.
• Low · Shell Command Execution via shell-words — bear/src/bin/wrapper.rs and related intercept modules using shell-words dependency. The project uses 'shell-words' for shell command parsing, which is used in wrapper.rs and other components that intercept and process compiler commands. Improper handling of shell parsing could lead to command injection if user inputs are not properly validated. Fix: Ensure all command-line arguments parsed with shell-words are properly validated and sanitized before execution. Use allowlists for valid compiler flags where possible. Add comprehensive input validation tests.
• Low · Process Interception with Elevated Privileges Risk — bear/src/intercept/supervise.rs, bear/src/intercept/wrapper.rs, intercept-preload module. The project intercepts compiler invocations via preload mechanisms and supervises child processes. If Bear runs with elevated privileges, this could potentially be exploited for privilege escalation attacks. Fix: Document privilege requirements clearly. Avoid running Bear with unnecessary elevated privileges. Implement strict validation of intercepted processes. Add logging and audit trails for process interception activities.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.