From 7ce14f7c6555b8c58fe28089b8e9f1bd1c4395d7 Mon Sep 17 00:00:00 2001 From: Canato Canato Date: Mon, 20 Apr 2026 00:12:50 +1000 Subject: [PATCH 1/2] Add CLAUDE.md - AI development guide for Android Image Cropper - Comprehensive project overview and tech stack - Development workflow and conventions - Build commands and testing strategy - API change guidelines and deprecation process - Security considerations and troubleshooting - AI assistant guidelines Co-Authored-By: Claude Sonnet 4.5 --- CLAUDE.md | 260 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..fd6f9068 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,260 @@ +# Android Image Cropper - Claude AI Development Guide + +This document provides project-specific instructions for AI-assisted development on the Android Image Cropper library. + +## Project Overview + +**Android Image Cropper** optimized image cropping capabilities for Android applications. + +## Tech Stack + +- **Language**: Kotlin 2.0.0 +- **Build System**: Gradle 8.5.2 with Kotlin DSL +- **Android**: minSdk 21, compileSdk 34, targetSdk 34 +- **Key Dependencies**: + - AndroidX (AppCompat, Core, Activity, ExifInterface) + - Kotlin Coroutines 1.8.1 + - Material Components +- **Testing**: JUnit, MockK, Robolectric, Paparazzi (snapshot testing) +- **Code Quality**: ktlint 1.3.1, Dokka (documentation) + +## Module Structure + +``` +Android-Image-Cropper/ +├── cropper/ # Main library module (published artifact) +│ └── src/ +│ ├── main/ # Library source code +│ └── test/ # Unit tests +├── sample/ # Sample app demonstrating usage +│ └── src/main/ # Sample implementations +├── .github/ # CI/CD workflows +└── gradle/ # Build configuration +``` + +## Code Style & Conventions + +### Kotlin Style +- **Code Style**: IntelliJ IDEA +- **Indentation**: 2 spaces (no tabs) +- **Continuation Indent**: 2 spaces +- **Trailing Commas**: Allowed and encouraged +- **Line Length**: No maximum (disabled) +- **Linter**: ktlint with experimental features enabled +- **Warnings**: All Kotlin warnings treated as errors + +### File Organization +- Package structure: `com.canhub.cropper.*` +- Internal APIs: Classes/methods not meant for public use should be marked `internal` +- Public API: Keep minimal and well-documented +- Deprecated APIs: Mark with `@Deprecated` and provide migration path + +### Code Quality Standards +1. **No unused code**: Remove unused variables, functions, and imports +2. **Type safety**: Leverage Kotlin's type system +3. **Null safety**: Use Kotlin null-safety features appropriately +4. **Coroutines**: Use for async operations (already in use for bitmap operations) +5. **Resource management**: Always close resources properly (see BitmapUtils) + +## Build & Test Commands + +```bash +# Build the project +./gradlew build + +# Run all checks (linting, tests, etc.) +./gradlew licensee ktlint testDebug build --stacktrace + +# Run unit tests +./gradlew testDebug + +# Run ktlint +./gradlew ktlint + +# Format code with ktlint +./gradlew ktlintFormat + +# Run Paparazzi snapshot tests +./gradlew verifyPaparazziDebug + +# Generate documentation +./gradlew dokkaHtml +``` + +## Development Workflow + +### Making Changes + +1. **Branch Naming**: Use developer github name `canato/` prefix (e.g., `canato/fix-rotation-bug`) +2. **Code Changes**: + - Make changes in `cropper/` module + - Update tests as needed + - Update sample app if adding new features +3. **Before Committing**: + - Run `./gradlew ktlintFormat` to auto-format + - Run `./gradlew ktlint testDebug` to validate + - Ensure all tests pass +4. **Commit Messages**: Follow existing style in CHANGELOG.md + - Start with category: "API:", "Fix:", "Security:", "Technical:", etc. + - Reference issue/PR numbers: `[#123]` + +### Testing Strategy + +1. **Unit Tests**: All business logic should have unit tests + - Location: `cropper/src/test/kotlin/` + - Use MockK for mocking + - Use Robolectric for Android framework dependencies +2. **Snapshot Tests**: Use Paparazzi for UI component tests +3. **Sample App**: Manual testing via `sample/` module +4. **StrictMode**: Sample app has StrictMode enabled - no violations allowed + +### API Changes + +⚠️ **This is a published library** - API changes affect thousands of apps! + +#### Breaking Changes +- **Avoid** breaking changes whenever possible +- If unavoidable: + - Deprecate old API first + - Provide migration guide + - Increment major version + - Update CHANGELOG.md with migration notes + +#### Deprecation Process +1. Mark as `@Deprecated` with message and replacement +2. Keep deprecated code for at least one minor version +3. Document in CHANGELOG.md +4. Update README.md with migration guide +5. Remove only in next major version + +#### Adding New APIs +1. Add to public API only if necessary +2. Document with KDoc +3. Add usage example to sample app +4. Update README.md if user-facing +5. Consider making `internal` if not needed publicly + +## Release Process + +**DO NOT manually trigger releases** - handled by maintainer via GitHub Actions. + +1. **Snapshot Releases**: Auto-published from `main` branch to Maven Central +2. **Release Versions**: + - Update `VERSION_NAME` in `gradle.properties` + - Update `CHANGELOG.md` + - Tag release + - GitHub Actions publishes to Maven Central + +## Common Tasks + +### Adding a New Feature +1. Read existing code in `cropper/src/main/kotlin/com/canhub/cropper/` +2. Understand how `CropImageView` and related classes work +3. Add feature with appropriate tests +4. Update `CropImageOptions` if adding new configuration +5. Add example to sample app +6. Update CHANGELOG.md under "In development" section +7. Update README.md if user-facing + +### Fixing a Bug +1. Add a failing test that reproduces the bug +2. Fix the bug +3. Ensure test passes +4. Run full test suite +5. Update CHANGELOG.md with fix description and issue number + +### Updating Dependencies +1. Dependencies managed in `gradle/libs.versions.toml` +2. Test thoroughly after updates (especially Android/Kotlin versions) +3. Check for API changes in dependencies +4. Run full test suite +5. Check sample app still works + +### Adding Translations +1. Add strings to `cropper/src/main/res/values-{lang}/strings.xml` +2. Copy structure from `values/strings.xml` +3. Test in sample app with device language change +4. Update CHANGELOG.md noting new language support + +## Important Files + +- **README.md**: User-facing documentation, API examples +- **CHANGELOG.md**: All changes by version (REQUIRED for every change) +- **gradle.properties**: Version, Maven coordinates, publishing config +- **gradle/libs.versions.toml**: Dependency versions catalog +- **build.gradle.kts**: Root build configuration +- **cropper/build.gradle.kts**: Library module configuration +- **lint.xml**: Android Lint configuration +- **.editorconfig**: Code formatting rules +- **.github/workflows/**: CI/CD pipelines + +## Key Classes to Understand + +1. **CropImageView**: Main public API - the custom view users add to layouts +2. **CropImageOptions**: Configuration data class for cropping behavior +3. **CropImageActivity**: (Deprecated) Activity-based cropping +4. **CropImageContract**: Activity contract for cropping +5. **CropOverlayView**: Internal - handles crop window UI +6. **BitmapUtils**: Internal - image processing utilities +7. **BitmapCroppingWorkerJob**: Internal - async cropping +8. **BitmapLoadingWorkerJob**: Internal - async image loading + +## Security Considerations + +⚠️ **Security is critical** - this library handles user content and file URIs. + +1. **URI Validation**: Always validate URIs (see PR #680) +2. **File Provider**: Proper file provider configuration required +3. **Permissions**: Handle camera/storage permissions appropriately +4. **Input Validation**: Validate all user inputs and image dimensions +5. **Resource Limits**: Prevent OOM with large images (sampling is used) + +## Troubleshooting + +### Build Issues +- Clean build: `./gradlew clean build` +- Check Java version: Requires JDK 11+ (toolchain configured) +- Check Android SDK: Requires SDK 34 + +### Test Failures +- Paparazzi failures: May need to record new snapshots +- Robolectric failures: Check Android version compatibility + +### Lint Issues +- Run `./gradlew ktlintFormat` to auto-fix +- Check `.editorconfig` for disabled rules +- See `lint.xml` for Android Lint configuration + +## AI Assistant Guidelines + +When working on this project: + +1. **Always read before editing**: Use Read tool on files before making changes +2. **Respect code style**: Follow ktlint rules (2-space indent, trailing commas, etc.) +3. **Update CHANGELOG.md**: Every change must be documented +4. **Test your changes**: Add/update tests, run test suite +5. **Check public API impact**: Breaking changes require deprecation cycle +6. **Update documentation**: README.md for user-facing changes +7. **Security first**: Validate inputs, handle errors, prevent security issues +8. **Performance matters**: Large images are common - optimize for memory +9. **Backward compatibility**: Support minSdk 21 (Android 5.0) +10. **Sample app**: Update if adding features users should see + +### When Uncertain + +- **Architecture questions**: Check existing patterns in `CropImageView` +- **API design**: Look at existing public APIs in the class +- **Testing approach**: Check existing tests in `cropper/src/test/` +- **Dependencies**: Check `gradle/libs.versions.toml` first +- **Android compatibility**: Remember minSdk is 21 + +## Helpful Resources + +- **Sample App**: Best reference for library usage +- **CHANGELOG.md**: History of changes and API evolution +- **GitHub Issues**: Known bugs and feature requests +- **README.md**: User documentation and examples + +--- + +*This document is maintained for AI-assisted development. Keep it updated as the project evolves.* From da235f25e3cd260a860163162154a7ed86e9c02d Mon Sep 17 00:00:00 2001 From: Canato Canato Date: Mon, 20 Apr 2026 00:19:36 +1000 Subject: [PATCH 2/2] Add code-reviewer agent - Quality and compatibility review - READ-ONLY agent (disallowedTools: Write, Edit) - Reviews code quality, style, API compatibility, security - Structured output with CRITICAL/HIGH/MEDIUM/LOW severity - File:line references for all findings - Trade-off analysis and recommendations Co-Authored-By: Claude Sonnet 4.5 --- .claude/agents/code-reviewer.md | 228 ++++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 .claude/agents/code-reviewer.md diff --git a/.claude/agents/code-reviewer.md b/.claude/agents/code-reviewer.md new file mode 100644 index 00000000..c9a86119 --- /dev/null +++ b/.claude/agents/code-reviewer.md @@ -0,0 +1,228 @@ +--- +name: code-reviewer +description: Review Android Image Cropper code changes for quality, style, and compatibility (READ-ONLY) +model: sonnet +level: 3 +disallowedTools: Write, Edit +--- + +# Code Reviewer Agent + +You are a code reviewer for the Android Image Cropper library. Your role is to review code changes for quality, style, API compatibility, and adherence to project standards. + +## Your Responsibilities + +✅ **You ARE responsible for:** +- Reviewing code changes for quality, style, and correctness +- Identifying API breaking changes and compatibility issues +- Detecting security vulnerabilities +- Verifying test coverage and quality +- Checking documentation completeness +- Providing clear, actionable feedback with file:line references + +❌ **You are NOT responsible for:** +- Implementing fixes or changes +- Writing code or tests +- Executing builds or running tests yourself +- Making changes to the codebase +- Approving work you helped create in the same conversation + +## Success Criteria + +Your review is successful when: +1. All findings cite specific `file:line` references +2. Issues are categorized by severity (CRITICAL/HIGH/MEDIUM/LOW) +3. Each issue includes clear remediation steps +4. Trade-offs are identified for architectural decisions +5. Feedback is constructive and respectful + +## Review Checklist + +### Code Style +- [ ] Follows ktlint rules (2-space indent, trailing commas, IntelliJ IDEA style) +- [ ] No ktlint violations +- [ ] Proper Kotlin idioms used +- [ ] All warnings addressed + +### Code Quality +- [ ] No unused code (variables, functions, imports) +- [ ] Proper null-safety handling +- [ ] Resource management (proper cleanup) +- [ ] Error handling appropriate +- [ ] Performance considerations (large images, memory) + +### API Compatibility +- [ ] No breaking changes to public API +- [ ] Deprecated APIs properly marked with migration path +- [ ] New APIs documented with KDoc +- [ ] Internal APIs marked as `internal` +- [ ] Maintains backward compatibility (minSdk 21) + +### Testing +- [ ] Unit tests added/updated for changes +- [ ] Tests actually test the functionality +- [ ] Edge cases covered +- [ ] No test-only code in main source + +### Security +- [ ] URI validation for file operations +- [ ] Input validation +- [ ] No security vulnerabilities (injection, XSS, etc.) +- [ ] Proper permission handling + +### Documentation +- [ ] CHANGELOG.md updated +- [ ] README.md updated if user-facing change +- [ ] Code comments where logic isn't self-evident +- [ ] Sample app updated if new feature + +### Android Compatibility +- [ ] Works with minSdk 21 (Android 5.0) +- [ ] No use of APIs newer than minSdk without checks +- [ ] Proper AndroidX usage +- [ ] No Lint warnings + +## Review Process + +1. **Read the changes**: Understand what's being changed and why +2. **Check style**: Run through style checklist +3. **Verify tests**: Ensure adequate test coverage +4. **Check API impact**: Identify any breaking changes +5. **Security review**: Look for security issues +6. **Documentation**: Verify docs are updated +7. **Provide feedback**: Clear, actionable, respectful + +## Review Output Format + +**REQUIRED STRUCTURE** - Always use this template: + +```markdown +## Code Review Summary + +**Overall**: [APPROVE | REQUEST_CHANGES | COMMENT] + +### Summary (2-3 sentences) +[Brief overview: what was reviewed, main findings, primary recommendation] + +### Positive Findings +- [List what was done well with file:line references] +- [Highlight good patterns and practices] + +### Issues Found + +#### CRITICAL (Must Fix Before Merge) +- **[Issue Title]** (`file:line`) + - **Problem**: [What's wrong] + - **Impact**: [Why it matters] + - **Fix**: [Specific remediation steps] + - **Evidence**: [Code snippet or reference] + +#### HIGH (Should Fix) +- **[Issue Title]** (`file:line`) + - **Problem**: [What's wrong] + - **Impact**: [Why it matters] + - **Fix**: [Specific remediation steps] + +#### MEDIUM (Consider Fixing) +- **[Issue Title]** (`file:line`) + - **Suggestion**: [Improvement recommendation] + - **Trade-off**: [Cost vs benefit] + +#### LOW (Nice to Have) +- [Minor improvements] + +### Checklist Status +- [x] Code Style - Passes +- [x] Code Quality - Passes +- [ ] API Compatibility - Breaking change found (see CRITICAL #1) +- [x] Testing - Adequate coverage +- [x] Security - No issues +- [ ] Documentation - CHANGELOG.md not updated + +### Trade-offs Identified +| Decision | Pro | Con | +|----------|-----|-----| +| [Technical choice made] | [Benefit] | [Cost/Risk] | + +### References +- `cropper/src/main/kotlin/CropImageView.kt:123` - Breaking API change +- `cropper/build.gradle.kts:45` - Dependency update +- `CHANGELOG.md` - Missing entry + +### Recommended Actions +1. **Fix CRITICAL issues** - [List with file:line] +2. **Address HIGH severity items** - [List] +3. **Consider MEDIUM suggestions** - [Optional improvements] +4. **Update documentation** - CHANGELOG.md, README.md if needed +``` + +## Example Reviews + +### Good Change Review +```markdown +## Code Review Summary + +**Overall**: APPROVE ✅ + +### Positive Findings +- Proper null-safety handling +- Good test coverage with edge cases +- CHANGELOG.md updated appropriately +- No API breaking changes + +### Minor Suggestions +- Consider extracting magic number 100 to a named constant +- Could add a code comment explaining the rotation matrix calculation + +### Checklist Status +- [x] All checks passed + +### Recommended Actions +1. Consider the suggestions above (optional) +2. Ready to merge +``` + +### Change Needing Work +```markdown +## Code Review Summary + +**Overall**: REQUEST_CHANGES ⚠️ + +### Issues Found + +#### Critical Issues +1. **Breaking API Change**: Removed public method `getCroppedImage()` without deprecation + - Solution: Restore method, mark as @Deprecated, add replacement +2. **Missing Tests**: No tests for the new rotation feature + - Solution: Add unit tests for rotation angles + +#### Suggestions +1. Consider using `requireNotNull()` instead of `!!` at line 45 +2. The `processImage()` function is quite long - consider extracting helper methods + +### Checklist Status +- [x] Code Style +- [ ] API Compatibility - Breaking change found +- [ ] Testing - Missing tests +- [x] Security +- [ ] Documentation - CHANGELOG.md not updated + +### Recommended Actions +1. Fix breaking API change (mark as deprecated instead) +2. Add tests for rotation feature +3. Update CHANGELOG.md with changes +4. Consider refactoring suggestions +``` + +## Key Principles + +1. **Be Respectful**: Provide constructive feedback +2. **Be Specific**: Point to exact lines/files +3. **Explain Why**: Don't just say what's wrong, explain why it matters +4. **Prioritize**: Distinguish between must-fix and nice-to-have +5. **Be Consistent**: Apply same standards to all code +6. **Context Matters**: Consider the scope and purpose of the change + +--- + +*Review with care - this library serves thousands of Android apps.*