Skip to content

Commit 7c79d4e

Browse files
razankv13claude
razankv13
and
claude
committed
docs: add Claude Code integration and project guidelines
Add CLAUDE.md with comprehensive project documentation for AI-assisted development including: - Architecture overview (CodeController, widget structure, module organization) - Development commands and CI pipeline requirements - Code style guidelines and naming conventions - Testing structure and multi-platform considerations Add .serena/ configuration for semantic code analysis tooling. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent f8549e7 commit 7c79d4e

File tree

9 files changed

+847
-0
lines changed

9 files changed

+847
-0
lines changed

‎.serena/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/cache

‎.serena/memories/architecture_patterns.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Flutter Code Editor - Architecture & Design Patterns
2+
3+
## Overall Architecture
4+
5+
This package follows a **modular, feature-based architecture** where functionality is organized by feature/concern rather than by layer.
6+
7+
## Key Architectural Patterns
8+
9+
### 1. Controller Pattern
10+
11+
**CodeController** is the central controller that:
12+
- Extends Flutter's `TextEditingController`
13+
- Manages the code state, folding, highlighting, and analysis
14+
- Acts as the interface between the UI and the business logic
15+
- Provides methods for code manipulation (folding, hiding sections, etc.)
16+
17+
```dart
18+
final controller = CodeController(
19+
text: '...',
20+
language: java,
21+
analyzer: DefaultLocalAnalyzer(),
22+
);
23+
```
24+
25+
### 2. Widget Composition
26+
27+
The package uses heavy widget composition:
28+
- **CodeField**: Main widget that composes multiple sub-widgets
29+
- **CodeTheme**: Theme provider using inherited widget pattern
30+
- Separate widgets for gutter, line numbers, folding handles, etc.
31+
32+
### 3. Pluggable Analyzers
33+
34+
The analyzer system uses a **plugin architecture**:
35+
- `Analyzer` abstract class defines the contract
36+
- Multiple implementations: `DefaultLocalAnalyzer`, `DartPadAnalyzer`
37+
- Users can implement custom analyzers
38+
- Note: This is experimental and may have breaking changes
39+
40+
### 4. Parser Pattern
41+
42+
**Named Section Parsing** uses the Strategy pattern:
43+
- `AbstractNamedSectionParser` defines the interface
44+
- `BracketsStartEndNamedSectionParser` is the built-in implementation
45+
- Allows custom parsing strategies by subclassing
46+
47+
### 5. Immutable Data Structures
48+
49+
The codebase heavily uses immutable data:
50+
- Code state is represented as immutable objects
51+
- Updates create new instances rather than mutating
52+
- Uses `equatable` package for value equality
53+
- Simplifies state management and debugging
54+
55+
### 6. Separation of Concerns
56+
57+
Each module has a specific responsibility:
58+
59+
- **code/**: Core data models (Code, TextRange, etc.)
60+
- **code_field/**: UI rendering and user interaction
61+
- **folding/**: Code block detection and folding logic
62+
- **highlight/**: Syntax highlighting integration
63+
- **analyzer/**: Code analysis and error detection
64+
- **autocomplete/**: Autocompletion logic and UI
65+
- **gutter/**: Line numbers, errors, and folding handles rendering
66+
- **named_sections/**: Section parsing and management
67+
- **history/**: Undo/redo functionality
68+
- **hidden_ranges/**: Hide/show code sections
69+
70+
## Data Flow
71+
72+
```
73+
User Input (CodeField)
74+
↓
75+
CodeController (manages state)
76+
↓
77+
Code (immutable data model)
78+
↓
79+
Rendering (CodeField + sub-widgets)
80+
```
81+
82+
### Text Editing Flow
83+
84+
1. User types in CodeField
85+
2. TextEditingController receives input
86+
3. CodeController processes changes
87+
4. Syntax highlighter parses code
88+
5. Analyzer checks for errors (if enabled)
89+
6. Folding detector updates foldable blocks
90+
7. UI re-renders with updated state
91+
92+
## Key Design Decisions
93+
94+
### 1. Extends TextEditingController
95+
96+
CodeController extends Flutter's built-in `TextEditingController`:
97+
- **Pros**: Compatible with existing Flutter text editing infrastructure
98+
- **Cons**: Must manage visible vs. full text separately (for folding/hiding)
99+
100+
### 2. Three Text Representations
101+
102+
- `text`: Visible text (excludes folded/hidden blocks)
103+
- `fullText`: Complete text including folded/hidden code
104+
- `value`: TextEditingValue with visible text and selection
105+
106+
### 3. Service Comments
107+
108+
Hidden markers in the text track folding/section boundaries:
109+
- Not visible to users
110+
- Included in `fullText`
111+
- Filtered from `text` and display
112+
113+
### 4. Read-Only Sections
114+
115+
Named sections can be locked:
116+
- Prevents user edits to specific code regions
117+
- Useful for educational/tutorial scenarios
118+
- Must use `fullText` to programmatically modify locked sections
119+
120+
### 5. Highlight Package Integration
121+
122+
Uses the `highlight` package for parsing:
123+
- Supports 100+ languages out of the box
124+
- Language-agnostic code folding for major languages
125+
- Themes from `flutter_highlight` package
126+
127+
## Widget Tree Structure
128+
129+
```
130+
CodeTheme (provides theme data)
131+
└─ CodeField
132+
├─ Gutter
133+
│ ├─ LineNumbers
134+
│ ├─ ErrorMarkers
135+
│ └─ FoldingHandles
136+
├─ TextField (actual text input)
137+
└─ AutocompletePopup
138+
```
139+
140+
## State Management
141+
142+
- **Local State**: Widget state using StatefulWidget
143+
- **Controller State**: CodeController holds the code state
144+
- **Theme State**: InheritedWidget for theme propagation
145+
- No external state management library (Redux, Bloc, Riverpod, etc.)
146+
147+
## Extension Points
148+
149+
The package is designed for extensibility:
150+
151+
1. **Custom Analyzers**: Implement `Analyzer` interface
152+
2. **Custom Section Parsers**: Subclass `AbstractNamedSectionParser`
153+
3. **Custom Themes**: Provide custom `CodeThemeData`
154+
4. **Custom Languages**: Use any language from `highlight` package
155+
156+
## Testing Strategy
157+
158+
- Unit tests for business logic
159+
- Widget tests for UI components
160+
- Tests mirror `lib/src/` structure in `test/src/`
161+
- Issue-specific tests in `test/issues/`
162+
- Mock external dependencies with `mocktail`
163+
164+
## Performance Considerations
165+
166+
- Use `const` constructors to reduce rebuilds
167+
- Lazy evaluation of folding blocks
168+
- Efficient text diffing for syntax highlighting
169+
- Virtualized scrolling for large files (via `scrollable_positioned_list`)
170+
- Linked scroll controllers for synchronized scrolling
171+
172+
## Multi-Platform Support
173+
174+
The package is designed to work on:
175+
- iOS
176+
- Android
177+
- Web
178+
- Desktop (Linux, macOS, Windows)
179+
180+
No platform-specific code that would limit portability.

‎.serena/memories/code_style_conventions.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Flutter Code Editor - Code Style & Conventions
2+
3+
## General Dart Principles
4+
5+
### Type Declarations
6+
- Always declare types for variables and functions (parameters and return values)
7+
- Avoid using `any` or dynamic types
8+
- Create necessary custom types instead of using primitives
9+
10+
### Language
11+
- Use English for all code and documentation
12+
13+
### Nomenclature
14+
- **Classes**: PascalCase (e.g., `CodeController`, `CodeField`)
15+
- **Variables/Functions/Methods**: camelCase (e.g., `foldAt`, `isLoading`)
16+
- **Files/Directories**: underscores_case (e.g., `code_field.dart`, `line_numbers/`)
17+
- **Constants**: UPPERCASE (e.g., `DEFAULT_TIMEOUT`)
18+
- **Boolean Variables**: Start with verbs (e.g., `isLoading`, `hasError`, `canDelete`)
19+
- **Functions**: Start with a verb (e.g., `executeValidation`, `saveState`, `isValid`)
20+
21+
### Well-known Abbreviations
22+
- `i`, `j` for loops
23+
- `err` for errors
24+
- `ctx` for contexts
25+
- `req`, `res`, `next` for middleware parameters
26+
27+
### File Organization
28+
- One export per file
29+
- No blank lines within a function
30+
- Complete words instead of abbreviations (except standard ones like API, URL)
31+
32+
## Function Guidelines
33+
34+
### Function Size and Purpose
35+
- Write short functions with a single purpose (< 20 instructions)
36+
- Use meaningful names combining verb + noun
37+
- For booleans: use `isX`, `hasX`, `canX`
38+
- For actions: use `executeX`, `saveX`
39+
40+
### Function Structure
41+
- Early checks and returns to avoid nesting
42+
- Extract utility functions to reduce complexity
43+
- Use higher-order functions (map, filter, reduce)
44+
- Use arrow functions for simple operations (< 3 instructions)
45+
- Use named functions for complex operations
46+
- Use default parameter values instead of null checks
47+
- Single level of abstraction per function
48+
49+
### Parameters
50+
- Reduce function parameters using RO-RO pattern (Receive Object, Return Object)
51+
- Use objects to pass multiple parameters
52+
- Declare necessary types for input and output
53+
54+
## Data Guidelines
55+
56+
### Immutability
57+
- Prefer immutability for data
58+
- Use `readonly` for data that doesn't change
59+
- Use `const` for literals that don't change
60+
- Utilize `const` constructors to reduce rebuilds
61+
62+
### Data Validation
63+
- Don't abuse primitive types
64+
- Encapsulate data in composite types
65+
- Avoid validation in functions; use classes with internal validation
66+
67+
## Class Guidelines
68+
69+
### SOLID Principles
70+
- Follow SOLID design principles
71+
- Prefer composition over inheritance
72+
- Declare interfaces to define contracts
73+
74+
### Class Size
75+
- Small classes with single purpose
76+
- Less than 200 instructions
77+
- Less than 10 public methods
78+
- Less than 10 properties
79+
80+
## Flutter-Specific Guidelines
81+
82+
### Widget Structure
83+
- Avoid deeply nesting widgets
84+
- Break down large widgets into smaller, reusable components
85+
- Keep widget tree flat for better performance and readability
86+
- Deeply nested widgets impact build times and memory usage
87+
88+
### Architecture
89+
- Use clean architecture principles
90+
- Use repository pattern for data persistence
91+
- Use pod pattern for business logic with Riverpod (Note: This package doesn't use Riverpod)
92+
- Controllers take methods as input and update UI state
93+
94+
### State Management
95+
- Manage state efficiently
96+
- Avoid unnecessary rebuilds
97+
- Use `const` constructors wherever possible
98+
99+
## Exception Handling
100+
101+
### When to Use Exceptions
102+
- Handle errors you don't expect
103+
- Catch exceptions only to:
104+
- Fix an expected problem
105+
- Add context
106+
- Otherwise use a global handler
107+
108+
## Linting Rules (from analysis_options.yaml)
109+
110+
### Enforced Rules
111+
- `unawaited_futures`: error
112+
- `unrelated_type_equality_checks`: error
113+
- `avoid_relative_lib_imports`: error
114+
- `always_use_package_imports`: warning
115+
- `always_declare_return_types`: true
116+
- `avoid_void_async`: true
117+
- `avoid_redundant_argument_values`: true
118+
- `avoid_unnecessary_containers`: true
119+
- `sort_constructors_first`: true
120+
- `prefer_const_constructors`: true
121+
- `prefer_final_fields`: true
122+
123+
### Disabled Rules
124+
- `depend_on_referenced_packages`: false
125+
- `overridden_fields`: false
126+
- `constant_identifier_names`: false
127+
- `non_constant_identifier_names`: false
128+
- `curly_braces_in_flow_control_structures`: false
129+
130+
### Ignored Warnings
131+
- `invalid_annotation_target`: ignore

‎.serena/memories/codebase_structure.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Flutter Code Editor - Codebase Structure
2+
3+
## Root Directory Structure
4+
5+
```
6+
/
7+
├── lib/ # Main source code
8+
├── test/ # Test files
9+
├── example/ # Example applications
10+
├── doc/ # Documentation
11+
├── .github/ # CI/CD workflows
12+
├── context/ # Context files
13+
├── .serena/ # Serena agent configuration
14+
├── pubspec.yaml # Package metadata and dependencies
15+
├── analysis_options.yaml # Linter and analyzer configuration
16+
├── README.md # Project documentation
17+
├── CHANGELOG.md # Version history
18+
└── .cursorrules # Cursor AI coding guidelines
19+
```
20+
21+
## Library Structure (lib/)
22+
23+
```
24+
lib/
25+
├── flutter_code_editor.dart # Main library export file
26+
└── src/ # Internal implementation
27+
├── analyzer/ # Code analysis (experimental)
28+
├── autocomplete/ # Autocompletion functionality
29+
├── code/ # Core code representation
30+
├── code_field/ # Main CodeField widget
31+
├── code_modifiers/ # Code modification utilities
32+
├── code_theme/ # Theme management
33+
├── folding/ # Code folding logic
34+
├── gutter/ # Line numbers and gutter UI
35+
├── hidden_ranges/ # Hidden code blocks
36+
├── highlight/ # Syntax highlighting
37+
├── history/ # Undo/redo functionality
38+
├── line_numbers/ # Line number rendering
39+
├── named_sections/ # Named section parsing
40+
├── service_comment_filter/ # Comment filtering
41+
├── single_line_comments/ # Comment handling
42+
├── util/ # Utility functions
43+
├── wip/ # Work in progress features
44+
└── sizes.dart # Size constants
45+
```
46+
47+
## Test Structure (test/)
48+
49+
```
50+
test/
51+
├── src/ # Unit tests mirroring lib/src
52+
└── issues/ # Tests for specific issues/bugs
53+
```
54+
55+
## Example Structure (example/)
56+
57+
The example directory contains sample Flutter applications demonstrating the package features:
58+
- `example/lib/` - Example code files
59+
- Platform-specific directories (ios/, android/, linux/)
60+
61+
## Key Files
62+
63+
- **lib/flutter_code_editor.dart**: Main entry point, exports public API
64+
- **pubspec.yaml**: Package configuration, dependencies, metadata
65+
- **analysis_options.yaml**: Linting rules and analyzer settings
66+
- **.cursorrules**: Code style guidelines for AI assistants
67+
- **.github/workflows/dart.yaml**: CI/CD pipeline configuration

0 commit comments

Comments
 (0)