--- /dev/null
+# Claude Code Configuration for Rspamd
+
+This directory contains Claude Code configuration and custom commands for the Rspamd project.
+
+## Files
+
+- **project_context.md** - Project-specific guidelines, code style, commit format, and release procedures
+- **settings.local.json** - Local permissions and settings for Claude Code
+- **commands/** - Custom slash commands for common Rspamd development tasks
+
+## Available Commands
+
+### Build and Test Commands
+
+#### `/build`
+Build and install Rspamd using the project's build system:
+- Navigate to `~/rspamd.build`
+- Run `ninja -j8 install`
+- Report build status
+
+#### `/test`
+Run Rspamd unit tests:
+- C/C++ tests: `test/rspamd-test-cxx`
+- Lua tests: `test/rspamd-test -p /rspamd/lua`
+- Report results
+
+#### `/build-and-test`
+Complete build and test workflow:
+- Build with ninja
+- Run all unit tests (C/C++ and Lua)
+- Comprehensive status report
+
+### Code Quality Commands
+
+#### `/check-code`
+Run all code quality checks (luacheck for Lua, clang-format check for C/C++).
+Focuses on modified files in the current working directory.
+
+#### `/format-code`
+Format C/C++ code according to project style using clang-format.
+For Lua files, suggests running luacheck but doesn't auto-fix.
+
+#### `/test-lua`
+Test Lua code changes:
+- Run luacheck on all Lua code
+- Suggest related functional tests to run
+- Check if test updates are needed
+
+### Git and Release Commands
+
+#### `/prepare-commit`
+Comprehensive pre-commit workflow:
+- Format code (C/C++)
+- Run luacheck (Lua)
+- Build project
+- Run unit tests
+- Stage formatted files
+- Suggest properly formatted commit message
+- Remind about GPG signing
+
+#### `/review-pr`
+Review a GitHub pull request for compliance with Rspamd standards:
+- Commit message format
+- Code style compliance
+- Test coverage
+- Project-specific requirements
+
+#### `/create-release`
+Interactive guide through the Rspamd release process:
+- Update ChangeLog
+- Update version in CMakeLists.txt
+- Create signed release commit
+- Create signed release tag
+- Update version for next dev cycle
+
+## Project Rules
+
+The configuration automatically enforces Rspamd project rules:
+
+### C/C++ Code
+- Must be formatted with clang-format before commit
+- No `std::unordered_map` or `std::hash` - use `contrib/ankerl/unordered_dense` instead
+- Custom printf format for logging (see `src/libutil/printf.h`)
+
+### Lua Code
+- Must pass luacheck before commit
+- `rspamd_logger` uses `%s` for all argument placeholders
+
+### Commit Messages
+All commits must follow the format: `[Tag] Description`
+
+Tags:
+- `[Feature]` - New features
+- `[Fix]` - Bug fixes
+- `[CritFix]` - Critical fixes
+- `[Minor]` - Minor changes (prefer for whitespace, nil checks, etc.)
+- `[Project]` - Project-wide changes
+- `[Rework]` - Major refactoring
+- `[Conf]` - Configuration changes
+- `[Test]` - Test changes
+- `[Rules]` - Spam detection rule changes
+
+### GPG Signing
+**ALL commits and tags MUST be GPG-signed:**
+```bash
+git commit -S -m "[Tag] Description"
+git tag -s X.Y.Z -m "Tag message"
+```
+
+## Usage
+
+Commands are invoked with a forward slash in Claude Code:
+
+```
+/check-code
+/prepare-commit
+/review-pr 5655
+```
+
+Claude Code will automatically reference `project_context.md` for all interactions in this project.
+
+## Permissions
+
+The following commands are pre-approved and won't require confirmation:
+- `gh pr view` / `gh pr diff` - View GitHub PRs
+- `luacheck` - Lint Lua code
+- `clang-format` - Format C/C++ code
+- `ninja` - Build project
+- `test/rspamd-test-cxx` - Run C/C++ unit tests
+- `test/rspamd-test` - Run Lua unit tests
+
+**Note**: `luac` is NOT used - Rspamd has its own test suite for syntax validation.
+
+## Integration with Cursor Rules
+
+The project also has `.cursor/rules/` directory with MDC files. The Claude Code configuration mirrors and extends those rules for compatibility.
--- /dev/null
+---
+description: Build Rspamd and run all unit tests
+---
+
+Complete build and test workflow for Rspamd:
+
+1. Build project:
+ - `cd ~/rspamd.build`
+ - `ninja -j8 install`
+2. If build succeeds, run unit tests:
+ - C/C++ tests: `test/rspamd-test-cxx`
+ - Lua tests: `test/rspamd-test -p /rspamd/lua`
+3. Report comprehensive results:
+ - Build status
+ - Test results
+ - Any failures or errors
+
+This is the standard pre-commit verification workflow.
--- /dev/null
+---
+description: Build and install Rspamd using ninja
+---
+
+Build and install Rspamd:
+
+1. Navigate to build directory: `~/rspamd.build`
+2. Run: `ninja -j8 install`
+3. Report build status and any errors
+4. If build succeeds, suggest running tests
+
+This uses the project's out-of-source build system with Ninja.
--- /dev/null
+---
+description: Run all code quality checks (luacheck, clang-format check)
+---
+
+Run the following code quality checks for Rspamd project:
+
+1. For Lua files: Run `luacheck src/plugins/lua/ lualib/ rules/` from project root
+2. For C/C++ files: Check if clang-format would make changes (dry-run)
+3. Report any issues found
+4. Suggest fixes if there are problems
+
+Focus on files that have been modified in the current git working directory.
--- /dev/null
+---
+description: Guide through creating a new Rspamd release
+---
+
+Guide through the Rspamd release process:
+
+1. Ask for the new version number (X.Y.Z)
+2. Show recent commits since last release to help write ChangeLog
+3. Help update ChangeLog with proper format:
+ ```
+ X.Y.Z: DD MMM YYYY
+ * [Feature] Feature description
+ * [Fix] Fix description
+ ```
+4. Update version in CMakeLists.txt
+5. Create release commit with full changelog:
+ ```
+ git commit --no-verify -S -m "Release X.Y.Z
+
+ * [Feature] ...
+ * [Fix] ..."
+ ```
+6. Create signed release tag:
+ ```
+ git tag -s X.Y.Z -m "Rspamd X.Y.Z
+
+ Main features:
+ * ...
+
+ Critical fixes:
+ * ..."
+ ```
+7. Create follow-up commit updating version for next dev cycle
+8. Remind to push commits and tags
+
+Walk through each step interactively.
--- /dev/null
+---
+description: Format code according to project style (clang-format for C/C++)
+---
+
+Format code files according to Rspamd project style:
+
+1. Identify modified C/C++ files in the current git working directory
+2. Run `clang-format -i` on those files using the `.clang-format` config
+3. Report what was formatted
+4. For Lua files, suggest running luacheck but don't auto-fix
+
+Make sure to use the `.clang-format` file in the project root.
\ No newline at end of file
--- /dev/null
+---
+description: Prepare for commit - build, test, format, check, suggest commit message
+---
+
+Complete pre-commit workflow for Rspamd project:
+
+1. Check git status to see what files are staged/modified
+2. **Code formatting and checks**:
+ - C/C++ files: Run clang-format
+ - Lua files: Run luacheck and report issues
+ - Stage formatted files if needed
+3. **Build project**:
+ - `cd ~/rspamd.build && ninja -j8 install`
+ - Report build status
+4. **Run unit tests** (if build succeeds):
+ - C/C++ tests: `test/rspamd-test-cxx`
+ - Lua tests: `test/rspamd-test -p /rspamd/lua`
+ - Report test results
+5. **Suggest commit message** following Rspamd format:
+ - Use appropriate tag: [Feature], [Fix], [Minor], [Test], [Conf], etc.
+ - Write clear, concise description
+ - Remind to use `git commit -S` for GPG signing
+6. Ask if the user wants to proceed with the commit
+
+Do NOT automatically commit - just prepare, verify, and suggest.
\ No newline at end of file
--- /dev/null
+---
+description: Review a GitHub PR for code quality and project standards
+---
+
+Review a GitHub pull request for Rspamd project compliance.
+
+Given a PR number or URL:
+
+1. Fetch PR details using `gh pr view <number>`
+2. Check PR title follows commit message format ([Tag] description)
+3. Review changed files for:
+ - C/C++ files: clang-format compliance, no std::unordered_map usage
+ - Lua files: luacheck compliance, proper rspamd_logger usage
+ - Commit messages: proper tags and GPG signatures
+4. Check if tests are included for new features
+5. Provide detailed feedback on what needs to be fixed
+6. Suggest improvements following project guidelines
+
+Be thorough but constructive in the review.
--- /dev/null
+---
+description: Test Lua code changes with luacheck and functional tests
+---
+
+Test Lua code changes in Rspamd:
+
+1. Run `luacheck src/plugins/lua/ lualib/ rules/` from project root
+2. Report any issues found
+3. If specific Lua files were modified, offer to run related functional tests
+4. Check if test files need to be updated for the changes
+5. Suggest creating new tests if adding new functionality
+
+Provide clear feedback on what needs to be fixed.
\ No newline at end of file
--- /dev/null
+---
+description: Run Rspamd unit tests (C/C++ and Lua)
+---
+
+Run Rspamd unit tests:
+
+1. First, ensure the project is built (`ninja -j8 install` in ~/rspamd.build)
+2. Run C/C++ unit tests: `test/rspamd-test-cxx`
+3. Run Lua unit tests: `test/rspamd-test -p /rspamd/lua`
+4. Report results from both test suites
+5. If tests fail, provide details on failures
+
+**Note**: Functional tests are run manually only, not part of this command.
--- /dev/null
+# Rspamd Project Context
+
+This document contains project-specific guidelines and requirements for the Rspamd mail processing system.
+
+## Project Overview
+
+Rspamd is a fast, free and open-source spam filtering system. The codebase consists of:
+- **C/C++ code**: Core functionality in `src/`
+- **Lua code**: Plugins, libraries, and rules in `src/plugins/lua/`, `lualib/`, `rules/`
+- **Configuration**: UCL-based configuration in `conf/`
+- **Tests**: Functional and unit tests in `test/`
+
+## Code Style and Quality
+
+### C and C++ Code
+
+- **Formatting**: Always run `clang-format` using the `.clang-format` file in project root before every commit
+- **Hash Maps**: DO NOT use C++ standard library hash maps (`std::unordered_map`, `std::hash`)
+ - Always use containers from `contrib/ankerl/unordered_dense` for maps/sets and related hashes
+- **Logging**: All debug logging functions use custom printf format implementation
+ - Read comments in `src/libutil/printf.h` before adding logging code
+
+### Lua Code
+
+- **Linting**: Run `luacheck src/plugins/lua/ lualib/ rules/` before every commit
+ - Change to project root directory before running luacheck
+ - Resolve all warnings except those explicitly permitted by project exceptions
+- **Logging**: `rspamd_logger` uses `%s` format strings for all argument placeholders
+
+## Commit Message Format
+
+All commits MUST follow structured format with tags:
+
+### Commit Tags
+
+- `[Feature]` - New features and capabilities
+- `[Fix]` - Bug fixes and corrections
+- `[CritFix]` - Critical bug fixes needing immediate attention
+- `[Minor]` - Minor changes, tweaks, or version updates (prefer for whitespace, nil checks, etc.)
+- `[Project]` - Project-wide changes, refactoring, or infrastructure
+- `[Rework]` - Major reworking of existing functionality
+- `[Conf]` - Configuration changes or updates
+- `[Test]` - Test additions or modifications
+- `[Rules]` - Changes to spam detection rules
+
+### Examples
+
+Single-line commits:
+```
+[Fix] Fix memory leak in dkim module
+[Feature] Add support for encrypted maps
+[Minor] Add missing cmath include
+```
+
+Multi-line commits (releases):
+```
+Release X.Y.Z
+
+* [Feature] First feature description
+* [Fix] First fix description
+```
+
+### GPG Signing
+
+**ALL commits and tags MUST be GPG-signed:**
+- Commits: `git commit -S`
+- Tags: `git tag -s <tagname>`
+- Verify: `git log --show-signature` or `git tag -v <tagname>`
+
+## Pre-commit Checks
+
+Pre-commit hooks verify:
+- Trailing whitespace
+- Line endings
+- ClangFormat
+- LuaCheck
+
+Use `--no-verify` only when necessary and ensure code quality manually.
+
+## Release Process
+
+### 1. Update ChangeLog
+
+Format:
+```
+X.Y.Z: DD MMM YYYY
+ * [Feature] Feature description
+ * [Fix] Fix description
+```
+
+Rules:
+- Date format: `DD MMM YYYY` (e.g., `30 Sep 2025`)
+- Each entry: ` * [Tag]` (two spaces, asterisk, space, tag)
+- Group by tag type
+- Keep descriptions concise
+
+### 2. Create Release Commit
+
+```bash
+git add ChangeLog
+git commit --no-verify -S -m "Release X.Y.Z
+
+* [Feature] Feature 1
+* [Fix] Fix 1
+..."
+```
+
+### 3. Create Release Tag
+
+```bash
+git tag -s X.Y.Z -m "Rspamd X.Y.Z
+
+Brief summary.
+
+Main features:
+* Feature 1
+
+Critical fixes:
+* Fix 1"
+```
+
+### 4. Update Version
+
+After release, increment version in `CMakeLists.txt`:
+```bash
+git add CMakeLists.txt
+git commit --no-verify -S -m "[Minor] Update version of rspamd to X.Y.Z"
+```
+
+## Version Numbers
+
+Defined in `CMakeLists.txt`:
+- **MAJOR**: Incompatible API changes
+- **MINOR**: New features (backward-compatible)
+- **PATCH**: Backward-compatible bug fixes
+
+## Build System
+
+### Build Directory
+- Build directory: `~/rspamd.build` (separate from source tree)
+- Use out-of-source builds with CMake + Ninja
+
+### Build and Install
+```bash
+cd ~/rspamd.build
+ninja -j8 install
+```
+
+### Testing
+
+**Unit Tests (C/C++):**
+```bash
+test/rspamd-test-cxx
+```
+
+**Unit Tests (Lua):**
+```bash
+test/rspamd-test -p /rspamd/lua
+```
+
+**Functional Tests:**
+- Run manually only (not automated in development workflow)
+- Located in `test/functional/`
+
+### Pre-commit Workflow
+1. Make changes in source directory
+2. Build: `cd ~/rspamd.build && ninja -j8 install`
+3. Run unit tests:
+ - C/C++: `test/rspamd-test-cxx`
+ - Lua: `test/rspamd-test -p /rspamd/lua`
+4. For Lua changes: `luacheck src/plugins/lua/ lualib/ rules/`
+5. For C/C++ changes: Check `clang-format` compliance
+6. Commit with GPG signature: `git commit -S -m "[Tag] Description"`
+
+**Note**: Do NOT use `luac` for syntax checking - use the project's test suite instead.
+
+## General Principles
+
+- Write clear, descriptive commit messages
+- One logical change per commit
+- Reference issue numbers when applicable
+- Keep commit history clean and meaningful
+- Do not introduce changes conflicting with these rules
+- When unsure, consult maintainers or in-code comments
--- /dev/null
+---
+description: "Rspamd: build system, testing, and development workflow"
+globs: ["**"]
+alwaysApply: true
+---
+
+# Build System
+
+## Build Directory
+- Build directory: `~/rspamd.build` (separate from source tree)
+- Use out-of-source builds with CMake + Ninja
+- **NEVER** build in source directory
+
+## Build and Install
+
+To build and install Rspamd:
+```bash
+cd ~/rspamd.build
+ninja -j8 install
+```
+
+## Testing
+
+### Unit Tests
+
+**C/C++ Unit Tests:**
+```bash
+test/rspamd-test-cxx
+```
+
+**Lua Unit Tests:**
+```bash
+test/rspamd-test -p /rspamd/lua
+```
+
+### Functional Tests
+- Located in `test/functional/`
+- Run **manually only** (not automated in development workflow)
+- Not part of pre-commit checks
+
+## Pre-commit Workflow
+
+Before committing changes:
+
+1. **Make changes** in source directory
+2. **Build**: `cd ~/rspamd.build && ninja -j8 install`
+3. **Run unit tests**:
+ - C/C++ tests: `test/rspamd-test-cxx`
+ - Lua tests: `test/rspamd-test -p /rspamd/lua`
+4. **Code quality checks**:
+ - Lua changes: `luacheck src/plugins/lua/ lualib/ rules/`
+ - C/C++ changes: Check `clang-format` compliance
+5. **Commit**: `git commit -S -m "[Tag] Description"`
+
+## Important Notes
+
+- **Do NOT use `luac`** for syntax checking - use the project's test suite instead
+- Always run tests after building before committing
+- Ensure all tests pass before creating pull requests
+- Functional tests are optional during development but required for releases
projects / thirdparty / rspamd.git / commitdiff
