Merge pull request #333 from domaframework/document/add-claude-code-document

Add CLAUDE.md

Author: xterao

.claude/setting.json

@@ -0,0 +1,164 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Essential Build Commands
+
+```bash
+# Build the plugin
+./gradlew build
+
+# Generate parser and lexer from BNF/Flex files (required before build)
+./gradlew generateLexer generateParser
+
+# Run tests
+./gradlew test
+
+# Run single test class
+./gradlew test --tests "org.domaframework.doma.intellij.formatter.SqlFormatterTest"
+
+# Code formatting and linting
+./gradlew spotlessApply
+./gradlew spotlessCheck
+
+# Run IntelliJ IDE with plugin for testing
+./gradlew runIde
+
+# Build plugin distribution
+./gradlew buildPlugin
+
+# Verify plugin compatibility
+./gradlew verifyPlugin
+```
+---
+## Architecture Overview
+
+This is an IntelliJ IDEA plugin that provides comprehensive development support for the Doma framework (a Java ORM). The plugin bridges the gap between DAO (Data Access Object) Java/Kotlin classes and their corresponding SQL template files.
+
+### Custom Language Support
+
+The plugin defines a custom language "DomaSql" that extends standard SQL with Doma-specific directives:
+- **Parser/Lexer**: Generated from `Sql.bnf` and `Sql.flex` files using GrammarKit
+- **Language Definition**: `SqlLanguage`, `SqlFileType`, `SqlParserDefinition`
+- **Custom Directives**: `/*%if*/`, `/*%for*/`, `/*# embedded */`, `/* bind variables */`
+
+### Key Components Architecture
+
+**Navigation & Actions**: Bidirectional jumping between DAO methods and SQL files
+- `action/dao/JumpToSQLFromDaoAction` - DAO method → SQL file
+- `action/sql/JumpToDaoFromSQLAction` - SQL file → DAO method
+- `gutter/` - Visual gutter icons for quick navigation
+
+**Code Analysis & Validation**:
+- `inspection/dao/` - DAO-related inspections (parameter types, return types, SQL file existence)
+- `inspection/sql/` - SQL-related inspections (bind variables, function calls, directive types)
+- `common/validation/result/` - Validation result types for all checks
+
+**IDE Integration**:
+- `contributor/sql/SqlCompletionContributor` - Code completion for SQL files
+- `formatter/` - SQL formatting with custom spacing and block handling
+- `reference/` - PSI reference resolution for symbols in SQL files
+- `refactoring/dao/` - Automatic SQL file/directory renaming when DAOs are refactored
+
+### Critical Relationships
+
+**DAO ↔ SQL Mapping**: The plugin uses naming conventions to map DAO methods to SQL files:
+- DAO class `com.example.EmployeeDao` maps to SQL directory `META-INF/com/example/EmployeeDao/`
+- Method `findByName` maps to SQL file `findByName.sql`
+
+**PSI Integration**: Heavily uses IntelliJ's PSI (Program Structure Interface):
+- `common/psi/PsiDaoMethod` - Core class representing DAO methods with SQL file resolution
+- `common/dao/DaoClass` - Utilities for detecting `@Dao` annotated classes
+- Custom PSI elements for SQL expressions and directives
+
+## Development Notes
+
+### Parser Generation
+Always run `generateLexer` and `generateParser` tasks after modifying `Sql.bnf` or `Sql.flex`. Generated files go to `src/main/gen/` and are excluded from version control but included in compilation.
+
+### Testing Strategy
+Tests use `DomaProjectDescriptor` to set up IntelliJ test environments with Doma dependencies. Test data is in `src/test/testData/` with separate directories for different feature tests.
+
+### Configuration Support
+The plugin reads `doma.compile.config` files to support custom ExpressionFunctions. This configuration is cached and invalidated based on file modification timestamps.
+
+### Formatter Implementation
+The SQL formatter uses a custom block-based approach with `SqlBlock` hierarchy and `SqlFormattingModelBuilder`. It's currently in preview mode with limited customization options.
+
+---
+# Tasks for Claude Code
+If you edit the code, run `./gradle spotless` and `/gradle check`.
+
+---
+# Code Guidelines
+Custom language implementations are written in Java, while plugin features are implemented in Kotlin.
+Custom language lexers and parsers are auto-generated using Grammar-Kit.
+
+## Architecture
+Plugin architecture organizes features into separate packages, with sub-packages categorized by class roles.
+Features are separated into packages for DAO classes and SQL files.
+## Package Structure
+```
+Feature Package
+├── dao
+│   └── AnAction subclass
+└── sql
+    └── AnAction subclass
+```
+
+### Actions
+Action functionality for navigating between DAO files and SQL files
+
+- **[Feature Package](src/main/kotlin/org/domaframework/doma/intellij/action)**
+- **Main Classes**: `AnAction` subclasses
+
+**Class Naming Rules**:
+Class names should have `Action` as a suffix.
+Classes should not have properties; necessary information should be obtained within functions.
+
+### LineMarker
+Line marker functionality for DAO methods and DOMA directives in SQL
+
+- **[Feature Package](src/main/kotlin/org/domaframework/doma/intellij/gutter)**
+- **Main Classes**: `LineMarkerProvider` subclasses
+  - Line marker class for DAO: `DaoLineMarkerProvider`
+  - Line marker class for SQL: `SqlLineMarkerProvider`
+  - **Class Naming Rules**: Use `Provider` as a suffix
+
+### Inspections
+Code inspection functionality for DAO methods and DOMA directives in SQL
+
+- **[Feature Package](src/main/kotlin/org/domaframework/doma/intellij/inspection)**
+- **Main Classes**: `InspectionTool`
+  - Code inspection class for DAO: `AbstractBaseJavaLocalInspectionTool` subclasses
+  - Code inspection class for SQL: `LocalInspectionTool` subclasses
+  - **Class Naming Rules**: Use `Inspection` as a suffix
+- **Related Classes**
+  - Processor: Classes that check inspection target elements. Provides common check processing for inspection targets that meet specific conditions
+    - **Class Naming Rules**: Use `Checker` or `Processor` as a suffix depending on the purpose
+  - Provider: Provider that returns a list of `InspectionTool` subclasses
+    - **Class Naming Rules**: Use `Provider` as a suffix
+  - Visitor: Classes that search for inspection target elements. Called from `InspectionTool`
+    - **Class Naming Rules**: Have the same name as the calling `InspectionTool` with `Visitor` as a suffix
+  - QuickFix: Classes that provide fix actions for inspection results
+    - Consists of a `Factory` object that provides quick fix objects and the main `QuickFix` object
+    - **Class Naming Rules**
+      - `Factory` object: Use `QuickFixFactory` as a suffix
+      - `QuickFix` object: Use `QuickFix` as a suffix
+  - [ValidationResult](src/main/kotlin/org/domaframework/doma/intellij/common/validation/result): Classes that provide error messages and highlights for code inspection results
+    - **Class Naming Rules**: Use `ValidationResult` as a suffix. Name classes according to the message resources to be displayed
+
+### Completion
+Code completion functionality for DOMA directive syntax in SQL
+- **[Feature Package](src/main/kotlin/org/domaframework/doma/intellij/contributor/sql)**
+- **Related Classes**
+  - CompletionContributor: Entry point for code completion
+    - **Class Naming Rules**: Use `CompletionContributor` as a suffix
+  - Provider: Classes that provide completion candidates in specific contexts
+    - **Class Naming Rules**: Use `CompletionProvider` as a suffix
+  - Processor: Classes that filter and transform completion candidates
+    - **Class Naming Rules**: Use `Processor` as a suffix
+  - [Handler](src/main/kotlin/org/domaframework/doma/intellij/common/sql/directive): Classes that generate suggestion candidates for each directive type
+    - **Class Naming Rules**: Use `Handler` as a suffix
+  - [Collector](src/main/kotlin/org/domaframework/doma/intellij/common/sql/directive/collector): Classes that collect directive suggestion candidates. Called from `Handler`
+    - **Class Naming Rules**: Use `Collector` as a suffix