Merge pull request #288 from poissoncorp/skill-csharp-sync

poissoncorp · web-flow · commit 556d1e06cc01 · 2026-04-09T16:18:14.000+02:00
Csharp sync skill
diff --git a/.claude/skills/csharp-sync/CONVENTIONS.md b/.claude/skills/csharp-sync/CONVENTIONS.md
@@ -0,0 +1,105 @@
+# Naming & Code Conventions
+
+## Naming map
+
+| C# | Python |
+|---|---|
+| `PascalCase` class | `PascalCase` class |
+| `PascalCase` method | `snake_case` method |
+| `PascalCase` property | `snake_case` attribute |
+| JSON keys in `ToJson()` | `"PascalCase"` in `to_json()` |
+| JSON keys in `FromJson()` | `"PascalCase"` in `from_json()` |
+| `IOperation<T>` | `IOperation[T]` |
+| `IMaintenanceOperation` | `IMaintenanceOperation` |
+| `IVoidMaintenanceOperation` | `VoidMaintenanceOperation` |
+| `null` | `None` |
+| `TimeSpan.FromDays(n)` | `timedelta(days=n)` |
+| `DateTime.UtcNow` | `datetime.datetime.now(datetime.timezone.utc)` — NEVER `utcnow()` |
+
+## Operation class pattern
+
+```python
+class MyNewOperation(IMaintenanceOperation[MyResult]):
+    def __init__(self, config: MyConfig):
+        self._config = config
+
+    def get_command(self, conventions: "DocumentConventions") -> RavenCommand[MyResult]:
+        return self._MyCommand(self._config)
+
+    class _MyCommand(RavenCommand[MyResult], RaftCommand):
+        def __init__(self, config: MyConfig):
+            super().__init__(MyResult)
+            self._config = config
+
+        def is_read_request(self) -> bool:
+            return False
+
+        def create_request(self, node: ServerNode) -> requests.Request:
+            request = requests.Request(
+                "PUT", f"{node.url}/databases/{node.database}/my-endpoint"
+            )
+            request.data = self._config.to_json()
+            return request
+
+        def set_response(self, response: str, from_cache: bool) -> None:
+            if response:
+                self.result = MyResult.from_json(json.loads(response))
+
+        def get_raft_unique_request_id(self) -> str:
+            return RaftIdGenerator.new_id()
+```
+
+## Model / DTO pattern
+
+```python
+class MyConfig:
+    def __init__(self, name: str = None, items: Optional[Dict] = None):
+        self.name = name
+        self.items = items
+
+    def to_json(self) -> dict:
+        result = {}
+        if self.name is not None:
+            result["Name"] = self.name
+        if self.items is not None:
+            result["Items"] = {k: v.to_json() for k, v in self.items.items()}
+        return result
+
+    @classmethod
+    def from_json(cls, json_dict: dict) -> "MyConfig":
+        obj = cls.__new__(cls)
+        obj.name = json_dict.get("Name")
+        # parse nested objects ...
+        return obj
+```
+
+## Exception wiring
+
+1. Create the class inheriting `RavenException` in `ravendb/exceptions/`.
+2. Register it in `exception_dispatcher.py` → `_EXCEPTION_MAP` using the **short C# type name** as key (e.g. `"SchemaValidationException"`).
+3. `RavenException.__init__` stores message as a plain string in `args[0]` — never a tuple.
+
+## Enum pattern
+
+```python
+class MyEnum(enum.Enum):
+    VALUE_ONE = "ValueOne"   # match the C# string / JSON value
+    VALUE_TWO = "ValueTwo"
+```
+
+## Import style
+
+- Absolute imports from `ravendb.*`.
+- Group: stdlib → third-party → project, separated by blank lines.
+- Use `TYPE_CHECKING` guard for circular-import-prone types.
+
+## Verifying against C# source
+
+When unsure about a field name, method signature, or serialization key, fetch the original C# file:
+
+```
+https://raw.githubusercontent.com/ravendb/ravendb/refs/heads/v7.2/src/Raven.Client/<path>.cs
+```
+
+
+
diff --git a/.claude/skills/csharp-sync/SKILL.md b/.claude/skills/csharp-sync/SKILL.md
@@ -0,0 +1,113 @@
+---
+name: csharp-sync
+description: Migrates RavenDB C# client features to the Python client. Use when porting C# diffs, patches, or test files to Python, batching sync work, or writing migration tests.
+---
+
+# C# → Python Client Sync
+
+Migrate features from the RavenDB C# client into this Python client codebase.
+Input is a raw `.patch` / `.diff` from the C# repo. Output is working Python code with tests.
+
+## Pipeline
+
+1. **Triage** — read the diff, list every changed file, group into batches
+2. **Implement** — port each batch following [CONVENTIONS.md](CONVENTIONS.md)
+3. **Test** — migrate or write tests following [TESTING.md](TESTING.md)
+
+## Reference sources
+
+When triaging or implementing, cross-reference with the upstream C# source and RavenDB docs.
+
+### C# source (GitHub raw)
+
+Base URL for the `v7.2` branch:
+```
+https://raw.githubusercontent.com/ravendb/ravendb/refs/heads/v7.2/src/Raven.Client/
+```
+
+To read a C# file, build the URL from its namespace path:
+- `Documents/Operations/Attachments/PutAttachmentOperation.cs`
+- `Documents/Commands/Batches/PutAttachmentCommandData.cs`
+- `Documents/Indexes/IndexDefinition.cs`
+- `Exceptions/Documents/DocumentDoesNotExistException.cs`
+
+To discover what's inside a directory, fetch the GitHub API:
+```
+https://api.github.com/repos/ravendb/ravendb/contents/src/Raven.Client/Documents/Operations?ref=v7.2
+```
+This returns a JSON array of `{name, path, type}` entries — use it to list files before fetching specific ones.
+
+For **tests**, the base path is:
+```
+https://raw.githubusercontent.com/ravendb/ravendb/refs/heads/v7.2/test/SlowTests/
+```
+With the API equivalent:
+```
+https://api.github.com/repos/ravendb/ravendb/contents/test/SlowTests?ref=v7.2
+```
+
+### RavenDB documentation
+
+Base URL: `https://docs.ravendb.net/7.2`
+
+Key sections to check during triage:
+- `document-extensions/attachments/` — attachment operations
+- `documents/schema-validation/` — JSON schema validation
+- `indexes/` — index definitions, schema in indexes
+- `ai-integration/` — AI / embeddings features
+
+Use docs to determine whether a C# change is:
+1. **A documented feature** → must be ported
+2. **C#-specific plumbing** (e.g. `IDisposable`, `Span<T>`) → skip
+3. **Related to a feature not yet synced** → defer to a later batch
+
+## Step 1 — Triage the diff
+
+1. Read the full diff. For each changed C# file write a one-line summary.
+2. For unfamiliar changes, **fetch the full C# source** from GitHub to understand context.
+3. **Check RavenDB docs** to confirm the feature is documented and understand its scope.
+4. **Filter out** changes that are C#-specific or relate to features not yet in the Python client.
+5. Group remaining changes into **batches** by feature area. Good boundaries:
+   - New operation class (e.g. `ConfigureRemoteAttachmentsOperation`)
+   - New model / DTO cluster (e.g. settings + configuration classes)
+   - New exception type + dispatcher wiring
+   - Test migration for an already-implemented feature
+6. Create a **checklist** — one `- [ ]` per batch, ordered by dependency (models → operations → tests).
+
+### Batch sizing
+
+- Target **≤ 300 lines of Python** per batch.
+- If a single C# file maps to > 300 lines, split by class or logical section.
+- Tests are their own batch, listed after the implementation batch they cover.
+
+## Step 2 — Implement each batch
+
+Follow the naming rules and patterns in [CONVENTIONS.md](CONVENTIONS.md).
+
+When porting a C# class, **always fetch the full source from GitHub** — diffs alone often lack constructor signatures, base classes, or `ToJson`/`FromJson` methods needed for a correct port.
+
+For every edit:
+1. Use `codebase-retrieval` to find ALL downstream callers, implementations, and tests.
+2. Update every affected file — missing a downstream change is a critical failure.
+3. After editing, verify imports resolve and no existing tests are broken.
+4. If unsure about a field or method, check the **RavenDB docs** for the canonical behavior.
+
+### Key files to touch per feature
+
+| What | Where |
+|---|---|
+| New operation / model | `ravendb/documents/operations/<feature>/__init__.py` |
+| New exception | `ravendb/exceptions/raven_exceptions.py` or subpackage |
+| Exception dispatcher map | `ravendb/exceptions/exception_dispatcher.py` |
+| DatabaseRecord fields | `ravendb/serverwide/database_record.py` |
+| IndexDefinition fields | `ravendb/documents/indexes/definitions.py` |
+| Statistics fields | `ravendb/documents/operations/statistics.py` |
+| Session-level changes | `ravendb/documents/session/` submodules |
+| Bulk insert changes | `ravendb/documents/bulk_insert_operation.py` |
+| Module exports | `ravendb/__init__.py` |
+
+## Step 3 — Write tests
+
+Follow the infrastructure and patterns in [TESTING.md](TESTING.md).
+
+
diff --git a/.claude/skills/csharp-sync/TESTING.md b/.claude/skills/csharp-sync/TESTING.md
@@ -0,0 +1,70 @@
+# Testing Conventions
+
+## Infrastructure
+
+- All tests extend `TestBase` from `ravendb/tests/test_base.py`.
+- `self.store` is pre-configured with a fresh database per test — no manual setup needed.
+- Run tests: `.venv1\Scripts\python.exe -m unittest <module.path> -v`
+
+## Assertion helpers
+
+| Helper | When to use |
+|---|---|
+| `self.assertRaisesWithMessageContaining(func, ExType, "substring")` | Server-side exceptions — the dispatcher includes the full C# stack trace, so exact match is fragile |
+| `self.assertRaisesWithMessage(func, ExType, "exact")` | Client-side exceptions only (e.g. `ValueError`) |
+| `self.assertFalse(x)` | Prefer over `assertIsNone` when the server may return `[]` instead of `null` |
+| `self.wait_for_indexing(self.store)` | Call after creating indexes, before querying |
+
+## Test file placement
+
+| C# test location | Python target |
+|---|---|
+| `SlowTests.Server.Documents.*` | `ravendb/tests/operations_tests/` |
+| `SlowTests.Client.*` | `ravendb/tests/jvm_migrated_tests/client_tests/` |
+| `FastTests.Client.Attachments.*` | `ravendb/tests/jvm_migrated_tests/attachments_tests/` |
+| `SlowTests.Issues.RavenDB_XXXXX` | `ravendb/tests/jvm_migrated_tests/issues_tests/` |
+
+## Test structure
+
+```python
+class TestMyFeature(TestBase):
+    def setUp(self):
+        super().setUp()
+
+    def test_should_do_something(self):
+        # 1. Arrange — configure the feature
+        config = MyConfig(name="test")
+        self.store.maintenance.send(ConfigureMyFeatureOperation(config))
+
+        # 2. Act
+        with self.store.open_session() as session:
+            session.store({"field": "value"}, "docs/1")
+            session.save_changes()
+
+        # 3. Assert
+        with self.store.open_session() as session:
+            doc = session.load("docs/1")
+            self.assertEqual("value", doc["field"])
+```
+
+## Index query projection pattern
+
+When an index projects custom fields, create a lightweight result class:
+
+```python
+class _IndexResult:
+    def __init__(self, Id=None, Errors=None):
+        self.Id = Id
+        self.Errors = Errors
+```
+
+Then query with `select_fields(_IndexResult, "Id", "Errors")`.
+
+## Common gotchas
+
+- **Datetime**: always `datetime.datetime.now(datetime.timezone.utc)`, never `utcnow()`.
+- **Empty vs None**: server may return `[]` instead of `null` for empty collections — use `assertFalse`/`assertTrue` not `assertIsNone`/`assertIsNotNone`.
+- **Exception messages**: the dispatcher wraps the full server error (message + stack trace) into the exception string — always use `assertRaisesWithMessageContaining` with a meaningful substring.
+- **`RavenException.__init__`**: stores message as plain string in `args[0]`, not `(message, cause)` tuple.
+- **Async operations**: use `store.maintenance.send_async(op)` → `op.wait_for_completion()` → `op.fetch_operations_status()["Result"]`.
+
diff --git a/.claude/skills/ravendb-docs-migration/SKILL.md b/.claude/skills/ravendb-docs-migration/SKILL.md
