From: Vsevolod Stakhov Date: Mon, 6 Oct 2025 11:34:07 +0000 (+0100) Subject: [Project] Add Claude Code and Cursor AI assistant configuration X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F5667%2Fhead;p=thirdparty%2Frspamd.git [Project] Add Claude Code and Cursor AI assistant configuration Add comprehensive configuration for AI development assistants: .claude/ - Claude Code configuration: - project_context.md: Project rules, code style, commit format, build system - commands/: Custom slash commands for development workflow - build, test, build-and-test: Build and testing commands - check-code, format-code, test-lua: Code quality commands - prepare-commit, review-pr, create-release: Git workflow commands - README.md: Documentation for all commands and features .cursor/rules/ - Cursor rules: - build-and-test.mdc: Build system and testing workflow documentation Features: - Automated code quality checks (luacheck, clang-format) - Build system integration (ninja in ~/rspamd.build) - Unit test execution (C/C++ and Lua tests) - Commit message validation and formatting - PR review assistance - Release process automation This enables AI assistants to follow Rspamd development practices and automate common development tasks. --- diff --git a/.claude/README.md b/.claude/README.md new file mode 100644 index 0000000000..2258ea89f3 --- /dev/null +++ b/.claude/README.md @@ -0,0 +1,136 @@ +# 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. diff --git a/.claude/commands/build-and-test.md b/.claude/commands/build-and-test.md new file mode 100644 index 0000000000..3457d50f56 --- /dev/null +++ b/.claude/commands/build-and-test.md @@ -0,0 +1,18 @@ +--- +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. diff --git a/.claude/commands/build.md b/.claude/commands/build.md new file mode 100644 index 0000000000..a58a6a7ef0 --- /dev/null +++ b/.claude/commands/build.md @@ -0,0 +1,12 @@ +--- +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. diff --git a/.claude/commands/check-code.md b/.claude/commands/check-code.md new file mode 100644 index 0000000000..0ec3af622e --- /dev/null +++ b/.claude/commands/check-code.md @@ -0,0 +1,12 @@ +--- +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. diff --git a/.claude/commands/create-release.md b/.claude/commands/create-release.md new file mode 100644 index 0000000000..6a55a71eef --- /dev/null +++ b/.claude/commands/create-release.md @@ -0,0 +1,36 @@ +--- +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. diff --git a/.claude/commands/format-code.md b/.claude/commands/format-code.md new file mode 100644 index 0000000000..aca6dcbbb6 --- /dev/null +++ b/.claude/commands/format-code.md @@ -0,0 +1,12 @@ +--- +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 diff --git a/.claude/commands/prepare-commit.md b/.claude/commands/prepare-commit.md new file mode 100644 index 0000000000..df2b6a8bea --- /dev/null +++ b/.claude/commands/prepare-commit.md @@ -0,0 +1,25 @@ +--- +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 diff --git a/.claude/commands/review-pr.md b/.claude/commands/review-pr.md new file mode 100644 index 0000000000..c53d5e8938 --- /dev/null +++ b/.claude/commands/review-pr.md @@ -0,0 +1,19 @@ +--- +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 ` +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. diff --git a/.claude/commands/test-lua.md b/.claude/commands/test-lua.md new file mode 100644 index 0000000000..e6eb7648fc --- /dev/null +++ b/.claude/commands/test-lua.md @@ -0,0 +1,13 @@ +--- +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 diff --git a/.claude/commands/test.md b/.claude/commands/test.md new file mode 100644 index 0000000000..6add36c899 --- /dev/null +++ b/.claude/commands/test.md @@ -0,0 +1,13 @@ +--- +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. diff --git a/.claude/project_context.md b/.claude/project_context.md new file mode 100644 index 0000000000..613931fa86 --- /dev/null +++ b/.claude/project_context.md @@ -0,0 +1,184 @@ +# 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 ` +- Verify: `git log --show-signature` or `git tag -v ` + +## 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 diff --git a/.cursor/rules/build-and-test.mdc b/.cursor/rules/build-and-test.mdc new file mode 100644 index 0000000000..f26abce16d --- /dev/null +++ b/.cursor/rules/build-and-test.mdc @@ -0,0 +1,60 @@ +--- +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