Skip to content

Commit 5b5acb0

Browse files
IvanMurzakIvanMurzak
committed
docs: add project guidelines for code style, architecture, and development practices
1 parent 35a52b2 commit 5b5acb0

2 files changed

Lines changed: 127 additions & 98 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Project Guidelines
2+
3+
## Code Style
4+
- **Language**: C# (LangVersion 11.0), .NET Standard 2.0/2.1, .NET 9.0
5+
- **Formatting**:
6+
- **Indentation**: 4 spaces.
7+
- **Braces**: Allman style (braces on new line).
8+
- **Namespaces**: Reverse domain style (e.g., `com.IvanMurzak.ReflectorNet`).
9+
- **Naming**:
10+
- Classes/Methods/Properties: `PascalCase`.
11+
- Private Fields: `camelCase` (e.g., `jsonSchema`).
12+
- Protected Fields: `_camelCase` (e.g., `_output`).
13+
- Locals/Params: `camelCase`.
14+
- **Documentation**: Extensive XML documentation (`///`) on public members.
15+
- **Reference**: See `ReflectorNet/src/Reflector/Reflector.cs` for style examples.
16+
17+
## Architecture
18+
- **Pattern**: Chain of Responsibility for object serialization/deserialization.
19+
- **Core Components**:
20+
- **Reflector** (`ReflectorNet/src/Reflector/`): Main entry point (partial class).
21+
- **Converters** (`ReflectorNet/src/Converter/`): `IReflectionConverter` implementations (Primitive, Generic, Array).
22+
- **Models** (`ReflectorNet/src/Model/`): `SerializedMember`, `MethodRef`.
23+
- **Key Files**:
24+
- `ReflectorNet/src/Reflector/Reflector.cs` (Core logic).
25+
- `ReflectorNet.Tests/src/BaseTest.cs` (Test base).
26+
27+
## Build and Test
28+
- **Restore**: `dotnet restore`
29+
- **Build**: `dotnet build --configuration Release`
30+
- **Test**: `dotnet test --configuration Release --verbosity normal`
31+
- **Pack**: `dotnet pack ReflectorNet/ReflectorNet.csproj --configuration Release --output ./packages`
32+
33+
## Project Conventions
34+
- **Logging**: Extensive use of `Microsoft.Extensions.Logging.ILogger`.
35+
- **Trace Logs**: Use specific emojis for trace stages (`Consts.Emoji`).
36+
- **Error Handling**: Prefer logging warnings and returning `null` over throwing exceptions for resolution failures.
37+
- **Converters**: Implement `SerializationPriority` to score applicability (0-10000+).
38+
- **Tests**:
39+
- Inherit from `BaseTest`.
40+
- Naming: `Method_State_ExpectedBehavior` (e.g., `TryUnstringify_JsonElement_Object_Stringified`).
41+
- Use `_output` for test logging.
42+
43+
## Integration Points
44+
- **Dependencies**: `Microsoft.Extensions.Logging`.
45+
- **Cross-Assembly**: `ReflectorNet.Tests.OuterAssembly` tests cross-assembly reflection.
46+
47+
## Security
48+
- **Reflection**: Handle dynamic method invocation and type resolution carefully.
49+
- **Validation**: Validate schema and inputs before reflection operations.

‎CLAUDE.md‎

Lines changed: 78 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -4,110 +4,90 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
44

55
## Development Commands
66

7-
### Build & Test
87
```bash
9-
# Restore dependencies
10-
dotnet restore
11-
128
# Build the solution
139
dotnet build --configuration Release
1410

15-
# Run tests
11+
# Run all tests (multi-TFM: net8.0 and net9.0)
1612
dotnet test --configuration Release --verbosity normal
1713

18-
# Build and pack for NuGet
14+
# Run a single test by fully qualified name
15+
dotnet test --configuration Release --filter "FullyQualifiedName~com.IvanMurzak.ReflectorNet.Tests.ClassName.MethodName"
16+
17+
# Run tests matching a pattern
18+
dotnet test --configuration Release --filter "FullyQualifiedName~SchemaTests"
19+
20+
# Pack for NuGet
1921
dotnet pack ReflectorNet/ReflectorNet.csproj --configuration Release --output ./packages
2022
```
2123

22-
### Project Structure
23-
- **ReflectorNet/**: Main library project - advanced .NET reflection toolkit
24-
- **ReflectorNet.Tests/**: Primary test suite using xUnit
25-
- **ReflectorNet.Tests.OuterAssembly/**: Test assembly for cross-assembly reflection scenarios
26-
- **ConsoleApp/**: Console application for testing and examples
27-
28-
## Architecture Overview
29-
30-
ReflectorNet implements a sophisticated **Chain of Responsibility** pattern for object serialization/deserialization:
31-
32-
### Core Components
33-
34-
#### Reflector Class (`src/Reflector/Reflector.cs`)
35-
- Main entry point providing serialization, deserialization, and object population capabilities
36-
- Partial class split across multiple files for different concerns
37-
- Uses converter registry system for extensible type handling
38-
39-
#### Converter System (`src/Converter/`)
40-
- **IReflectionConverter**: Interface defining converter contract
41-
- **Chain of Responsibility**: Multiple specialized converters handle different types:
42-
- `PrimitiveReflectionConverter`: Built-in .NET types (int, string, DateTime, etc.)
43-
- `GenericReflectionConverter`: Custom classes and structs
44-
- `ArrayReflectionConverter`: Arrays and collections
45-
- `BaseReflectionConverter`: Abstract base with common functionality
46-
47-
#### Key Models (`src/Model/`)
48-
- **SerializedMember**: Type-preserving serialized object representation
49-
- **MethodRef**: Method reference for dynamic discovery and invocation
50-
- **MethodData**: Method metadata and parameter information
51-
52-
#### Utilities (`src/Utils/`)
53-
- **JsonSchema**: JSON Schema generation for types and methods
54-
- **JsonSerializer**: ReflectorNet-optimized JSON serialization
55-
- **TypeUtils**: Type resolution and naming utilities
56-
- **StringUtils**: String manipulation and formatting
57-
58-
### Target Frameworks
59-
- **.NET Standard 2.0** & **2.1**: Broad compatibility
60-
- **.NET 9.0**: Latest framework features
61-
- **LangVersion 11.0**: Modern C# language features
62-
- **Nullable enabled**: Strict null reference types
63-
64-
## Key Features Implementation
65-
66-
### Method Discovery & Invocation
67-
- Fuzzy matching algorithms with configurable similarity levels (0-6)
68-
- Dynamic method binding with parameter type resolution
69-
- Support for partial method names and namespace matching
70-
- Cross-assembly method discovery capabilities
71-
72-
### Object Population System
73-
- In-place object updates without replacement
74-
- Selective member population with BindingFlags control
75-
- Hierarchical population with depth tracking
76-
- Comprehensive error reporting with detailed logging
77-
78-
### JSON Schema Generation
79-
- OpenAPI-compatible schema generation
80-
- Method parameter schemas for dynamic invocation
81-
- Type introspection with reference optimization
82-
- Support for complex nested types and collections
83-
84-
## Development Patterns
85-
86-
### Converter Priority System
87-
Each converter implements `SerializationPriority(Type type)` returning a score (0-10000+):
88-
- Higher scores indicate better type compatibility
89-
- Automatic selection of optimal converter for each type
90-
- Considers inheritance distance for matching
91-
92-
### Error Handling
93-
- Hierarchical error reporting with depth-based indentation
94-
- StringBuilder-based error accumulation
95-
- Microsoft.Extensions.Logging integration throughout
96-
- Comprehensive validation at each operation level
97-
98-
### Extensibility
99-
- Custom converter registration via `Reflector.Converters.Add()`
100-
- Override priority scoring for specialized type handling
101-
- Pluggable serialization behavior for any .NET type
102-
103-
## Testing Strategy
104-
- **xUnit** testing framework
105-
- Cross-assembly testing with separate test assembly
106-
- Comprehensive coverage of serialization scenarios
107-
- Performance and compatibility testing across target frameworks
108-
109-
## Package Information
110-
- **NuGet Package**: `com.IvanMurzak.ReflectorNet`
111-
- **Current Version**: 1.0.5
112-
- **Dependencies**: Microsoft.Extensions.Logging 9.0.7, System.Text.Json 9.0.7
113-
- **Runtime Identifiers**: Supports Windows, Linux, and macOS (x64, x86, ARM64)
24+
## Project Layout
25+
26+
- **ReflectorNet/** - Main library (NuGet: `com.IvanMurzak.ReflectorNet`)
27+
- **ReflectorNet.Tests/** - xUnit test suite
28+
- **ReflectorNet.Tests.OuterAssembly/** - Separate assembly used by tests for cross-assembly reflection scenarios
29+
- **ConsoleApp/** - Console app for manual testing
30+
31+
## Target Frameworks & Language
32+
33+
- **Library**: `netstandard2.1`, `net8.0`, `net9.0` — LangVersion `10.0`
34+
- **Tests**: `net8.0`, `net9.0` — LangVersion `11.0`
35+
- Nullable enabled, ImplicitUsings disabled throughout
36+
- Root namespace: `com.IvanMurzak.ReflectorNet`
37+
38+
## Architecture
39+
40+
ReflectorNet is a reflection toolkit for AI-driven .NET scenarios — fuzzy method discovery, type-preserving serialization, and dynamic invocation.
41+
42+
### Reflector (partial class, split across 10 files)
43+
44+
`Reflector` is the main entry point in `src/Reflector/`. Each concern is a separate partial file:
45+
46+
| File | Responsibility |
47+
|------|---------------|
48+
| `Reflector.cs` | Constructor, reference resolution |
49+
| `Reflector.Serialize.cs` | Object → `SerializedMember` |
50+
| `Reflector.Deserialize.cs` | `SerializedMember` → object |
51+
| `Reflector.Populate.cs` | In-place object updates |
52+
| `Reflector.FindMethod.cs` | Fuzzy method discovery (match levels 1-6) |
53+
| `Reflector.CallMethod.cs` | Dynamic method invocation |
54+
| `Reflector.Json.cs` | JSON serialization integration |
55+
| `Reflector.Registry.cs` | Converter registry (nested `Registry` class) |
56+
| `Reflector.DefaultValue.cs` | Default value resolution |
57+
| `Reflector.Equals.cs` | Deep equality comparison |
58+
| `Reflector.Error.cs` | Hierarchical error formatting |
59+
60+
### Converter System (Chain of Responsibility)
61+
62+
Located in `src/Converter/`. The `Registry` selects the best converter by querying each for `SerializationPriority(Type)` — highest score wins.
63+
64+
**Reflection converters** (`src/Converter/Reflection/`):
65+
- `BaseReflectionConverter<T>` — abstract base (partial: `.Serialize`, `.Deserialize`, `.Populate`, `.DefaultValue`)
66+
- `PrimitiveReflectionConverter` — built-in types (int, string, DateTime, etc.)
67+
- `GenericReflectionConverter<T>` — custom classes/structs (fallback)
68+
- `ArrayReflectionConverter` — arrays and collections (partial: `.Deserialize`)
69+
- `TypeReflectionConverter`, `AssemblyReflectionConverter` — System.Type, Assembly
70+
- `LazyGenericReflectionConverter` — runtime type resolution for optional dependencies
71+
- `IgnoreFieldsAndPropertiesReflectionConverter` — selective member exclusion
72+
73+
**JSON converters** (`src/Converter/Json/`): System.Text.Json converters for many .NET types. `IJsonSchemaConverter` interface enables custom JSON Schema generation.
74+
75+
### Key Models (`src/Model/`)
76+
77+
- `SerializedMember` — type-preserving intermediate representation (partial: `.Static`)
78+
- `MethodRef` — method reference for fuzzy discovery
79+
- `MethodData` — method metadata and parameters
80+
- `SerializationContext` / `DeserializationContext` — state during (de)serialization
81+
82+
### Thread Safety
83+
84+
Registry uses `ConcurrentBag`/`ConcurrentDictionary` with a cache-replacement invalidation pattern (replace entire dictionary reference rather than clearing) for thread-safe converter and blacklist cache management.
85+
86+
## CI/CD
87+
88+
- **PR workflow** (`pull_request.yml`): build + test on ubuntu with .NET 8.0 + 9.0, publishes trx test results
89+
- **Release workflow** (`release.yml`): triggered on push to main — reads version from `ReflectorNet.csproj` `<Version>`, creates GitHub release tag, publishes NuGet package. Version bump = new release.
90+
91+
## Versioning
92+
93+
Version is defined in `ReflectorNet/ReflectorNet.csproj` `<Version>` element. Bumping it and merging to main triggers a NuGet publish.

0 commit comments

Comments
 (0)