Add CLAUDE.md for project guidance and build commands

Author: sean7218

CLAUDE.md

@@ -0,0 +1,84 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Bazel Build Server Protocol (BSP) implementation for Swift and iOS projects that integrates with SourceKit LSP. It allows SourceKit to work with Bazel-based Swift projects, providing IDE features like syntax highlighting, jump to definition, auto-complete, etc.
+
+## Build Commands
+
+### Swift Package Manager Commands
+- `swift build` - Build the project in debug mode
+- `swift build --configuration release` - Build release version
+- `swift run bazel-build-server` - Run the build server executable
+- `swift test` - Run all tests using Swift Testing framework
+- `swift package clean` - Clean build artifacts
+
+### Makefile Commands
+- `make build` - Build debug version (equivalent to `swift build`)
+- `make release` - Build release version
+- `make run` - Build and run the executable
+- `make clean` - Clean build artifacts
+- `make install` - Install release binary to `/usr/local/bin`
+- `make test-harness` - Build and copy binary to TestHarness directory
+
+### Bazel Commands (in TestHarness directory)
+- `bazel build //App:App` - Build the test app
+- `bazel test //...` - Run all Bazel tests
+- `bazel query //...` - Query all targets
+
+## Architecture
+
+### Core Components
+
+**Main Executable (`Sources/BazelBuildServer/`)**
+- `BazelBuildServer.swift` - Entry point with CLI argument parsing and logging setup
+
+**Build Server Library (`Sources/BazelBuildServerLib/`)**
+- `BuildServer.swift` - JSON-RPC communication handler, reads from stdin/stdout
+- `RequestHandler.swift` - Processes BSP requests (initialize, compile, etc.)
+- `BSPTypes.swift` - Build Server Protocol type definitions
+- `StreamLogHandler.swift` - Custom logging implementation
+
+**Action Query System (`Sources/ActionQuery/`)**
+- `ActionQuery.swift` - Executes Bazel aquery commands with caching
+- `BazelTarget.swift` - Represents Bazel build targets
+- `QueryResult.swift` - Parses Bazel query output
+
+**Supporting Libraries**
+- `Sources/BSPError/` - Error handling types
+- `Sources/ShellCommand/` - Shell command execution utilities
+- `Sources/QueryParser/` - Protobuf-based query parsing
+
+### Key Patterns
+
+1. **JSON-RPC Communication**: The build server communicates via JSON-RPC over stdin/stdout following LSP patterns
+2. **Caching Strategy**: Bazel query results are cached in `~/.bazel-sourcekit-bsp/` with background refresh
+3. **Concurrent Processing**: Uses DispatchQueue for thread-safe target management
+4. **Structured Logging**: Dual logging to file (`~/bazel-build-server.log`) and activity log (`~/.bazel-sourcekit-bsp/activity.log`)
+
+### Configuration
+
+The build server is configured via `buildServer.json` files that specify:
+- Executable path and arguments
+- Target Bazel targets to track
+- Index database path
+- Additional aquery arguments
+
+## Test Harness
+
+The `TestHarness/` directory contains a complete Bazel workspace for testing:
+- iOS app target (`//App:App`)
+- Various Swift libraries with different dependency patterns
+- External dependencies managed via `MODULE.bazel`
+- Custom BUILD.bazel files for third-party dependencies
+
+## Testing
+
+Tests use the Swift Testing framework (not XCTest). Key test targets:
+- `ActionQueryTests` - Tests query parsing with JSON/text fixtures
+- `ShellCommandTests` - Tests shell command execution
+- `QueryParserTests` - Tests protobuf query parsing
+
+Run tests with `swift test` or target specific tests like `swift test --filter ActionQueryTests`.

README.md

@@ -6,6 +6,16 @@ This allows you to get SourceKit working for Swift projects that use the Bazel b
 
 SourceKit is a language server that provides syntax highlight, jump to definition, auto complete, etc.
 
+## Installation
+
+1. clone the project and run swift build, the server executable will be store in the `.build/arm64-apple-macosx/debug/bazel-build-server`
+2. edit the buildServer.json under the TestHarness folder by changing the executable path
+3. if you use global_index_store, be sure the change the path to the `.index-db`
+4. open TestHarness folder with `code TestHarness`
+5. the bazel-build-server.log is stored at the user home directory `~/bazel-build-server.log`
+
+You can use the example buildServer.json inside the TestHarness for your project and make sure you specify the target name `//YourTarget:YourTarget`
+
 ### Recommended plugins
 
 - [Swift format](https://github.com/nicklockwood/SwiftFormat). Formats your swift code "on save".