feat: add merge() method + basedpyright type checking (#41)

* fix: prevent nested dict flattening in _create_at

Op.merge_into flattens nested dicts to the wrong indentation level when
creating intermediate keys (e.g. upsert('parent', 'child', value={'x': 1})).
Fix by using add(key, None) + replace(value) which correctly serializes
the full nested structure.

Adds a regression test that fails without the fix.

* refactor: add remove_extra flag to _compute_patches

* feat: add Document.merge() method

* test: add merge edge case tests

Add test classes for list replacement, type promotion, path creation, and no-op merge scenarios. Fix _create_at to correctly handle nested dict values by using placeholder+replace instead of direct Op.add which flattens nested structures.

* feat: add Editor.merge() delegate

* docs: add deep merge design spec and implementation plan

* refactor: address review feedback

- Short-circuit list diffing in merge (replace entirely per spec)
- Add root-exists comment to merge() for consistency with sync()
- Add flow sequence tests to test_merge.py

* fix: use doc in merge fallback, add equality guard, add error test

* fix: raise NodeTypeError on scalar traversal, remove broken spec reference

* fix: improve merge comment clarity and NodeTypeError message format

* refactor: address review - improve error path, remove dead flow-seq code, rewrite docstring, introduce DiffMode enum

* feat: add basedpyright type checking

- Add basedpyright as dev dependency
- Add typing_extensions as runtime dependency (for @OverRide on py3.10/3.11)
- Configure [tool.basedpyright] with appropriate suppressions
- Add basedpyright hook to .pre-commit-config.yaml (runs in CI via prek)
- Switch to relative imports to break import cycles
- Remove redundant Component.key()/Component.index() static factories
- Retype _create_at child_keys as tuple[str, ...] with _ensure_str_keys
- Make normalize_keys and compute_patches public (with tests)
- Add @OverRide decorators and type annotations for class attributes
- Enable reportUnusedCallResult, reportUnknownMemberType,
  reportUnnecessaryIsInstance, reportImplicitStringConcatenation

* fix: update DiffMode docstring to reference compute_patches

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: nathanjmcdougall

.importlinter

@@ -18,5 +18,3 @@ exhaustive_ignores =
     _display
     _types
 ignore_imports =
-    yamltrip.document -> yamltrip
-    yamltrip.sync -> yamltrip

.pre-commit-config.yaml

@@ -55,6 +55,20 @@ repos:
         entry: uv run --frozen cargo clippy --all-targets --no-default-features -- -D warnings
         language: system
         pass_filenames: false
+  - repo: local
+    hooks:
+      - id: basedpyright
+        name: basedpyright
+        always_run: true
+        entry: uv run --frozen --offline basedpyright
+        language: system
+        types: [python]
+        pass_filenames: false
+        require_serial: true
+  - repo: https://github.com/jendrikseipp/vulture
+    rev: v2.16
+    hooks:
+      - id: vulture
   - repo: https://github.com/codespell-project/codespell
     rev: v2.4.2
     hooks:

doc/specs/2026-05-22-deep-merge-design.md

@@ -0,0 +1,123 @@
+# Design: Deep Merge (`merge()`)
+
+**Date:** 2026-05-22  
+**Status:** Approved
+
+## Summary
+
+Add a `merge()` method that recursively merges a value into an existing
+mapping without removing keys not present in the target. Lists replace
+entirely (list identity is ambiguous); only mapping keys get additive
+treatment.
+
+## Semantics
+
+| Current type | Target type | Behavior |
+|---|---|---|
+| mapping | mapping | Recurse: update matching keys, add new keys, never remove existing keys |
+| list | list | Replace the list entirely |
+| scalar | mapping | Replace scalar with mapping (promote) |
+| mapping | scalar | Replace mapping with scalar |
+| any | any (equal) | No-op |
+| missing | any | Create path + set value (delegate to `upsert()`) |
+
+Full-depth recursion always. No configurable depth parameter.
+
+## Public API
+
+```python
+# Document (immutable, returns new Document)
+doc = doc.merge(*keys, value={"debug": False, "timeout": 30})
+
+# Editor (mutable context manager)
+with edit("config.yaml") as ed:
+    ed.merge("settings", value={"debug": False, "timeout": 30})
+```
+
+Signature: `merge(self, *keys: KeyPart, value: Any) -> Document`
+
+Matches `sync()` signature exactly.
+
+## Error behavior
+
+- `NodeTypeError` if path traverses through a scalar/list where a mapping
+  is expected
+- `PatchError` on Rust-level failures (same fallback as `sync()`)
+- No new error types
+
+## Scope
+
+- No new Rust code — reuses existing patch primitives
+- No new error types
+- `sync()` behavior unchanged
+- Available on both `Document` and `Editor`
+
+## Examples
+
+```python
+from yamltrip import loads
+
+doc = loads("""
+settings:
+  debug: true
+  log_level: info
+  custom_setting: 42
+""")
+
+# Merge ensures debug+timeout exist without removing log_level/custom_setting
+doc = doc.merge("settings", value={"debug": False, "timeout": 30})
+
+# Result:
+# settings:
+#   debug: false
+#   log_level: info
+#   custom_setting: 42
+#   timeout: 30
+```
+
+```python
+# Lists replace entirely
+doc = loads("""
+plugins:
+  - eslint
+  - prettier
+""")
+
+doc = doc.merge("plugins", value=["stylelint"])
+
+# Result:
+# plugins:
+#   - stylelint
+```
+
+```python
+# Nested merge
+doc = loads("""
+database:
+  host: localhost
+  credentials:
+    user: admin
+    password: secret
+""")
+
+doc = doc.merge("database", value={"credentials": {"user": "deploy"}, "port": 5432})
+
+# Result:
+# database:
+#   host: localhost
+#   credentials:
+#     user: deploy
+#     password: secret
+#   port: 5432
+```
+
+## Testing
+
+- Mapping merge: keeps extra keys, updates matching, adds new
+- Nested mapping merge: recurses correctly
+- List replacement: lists in target replace entirely
+- Scalar-to-mapping promotion: works
+- Missing path creation: delegates to upsert
+- No-op when values equal: returns same Document instance
+- Flow sequence handling: same fallback as sync
+- Editor delegation: verify Editor.merge works

pyproject.toml

@@ -18,10 +18,13 @@ classifiers = [
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
 ]
-dependencies = []
+dependencies = [
+  "typing-extensions>=4.4.0",
+]
 
 [dependency-groups]
 dev = [
+  "basedpyright>=1.39.6",
   "codespell>=2.4.2",
   "deptry>=0.25.1",
   "import-linter>=2.11",
@@ -32,6 +35,7 @@ dev = [
   "ruff>=0.15.12",
   "tomli>=2.4.1",
   "ty>=0.0.35",
+  "vulture>=2.16",
 ]
 test = [
   "coverage[toml]>=7.14.0",
@@ -75,3 +79,30 @@ report.exclude_also = [
   "raise NotImplementedError",
 ]
 report.omit = [ "*/pytest-of-*/*" ]
+
+[tool.basedpyright]
+reportAny = false
+reportExplicitAny = false
+reportUnknownArgumentType = false
+reportUnknownVariableType = false
+
+[[tool.basedpyright.executionEnvironments]]
+root = "tests"
+reportMissingParameterType = false
+reportPrivateUsage = false
+reportUnannotatedClassAttribute = false
+reportUnknownLambdaType = false
+reportUnknownMemberType = false
+reportUnknownParameterType = false
+reportUnreachable = false
+reportUnusedCallResult = false
+reportUnusedExpression = false
+reportUnusedFunction = false
+reportUnusedParameter = false
+
+[tool.vulture]
+paths = [ "src/yamltrip" ]
+ignore_names = [
+  "dump",     # Public API method on Document
+  "original", # Public API property on Editor
+]

src/types.rs

@@ -76,22 +76,10 @@ pub enum PyComponent {
 
 #[pymethods]
 impl PyComponent {
-    #[staticmethod]
-    fn key(name: &str) -> Self {
-        Self::Key {
-            name: name.to_string(),
-        }
-    }
-
-    #[staticmethod]
-    fn index(index: usize) -> Self {
-        Self::Index { index }
-    }
-
     fn __repr__(&self) -> String {
         match self {
-            Self::Key { name } => format!("Component.key('{name}')"),
-            Self::Index { index } => format!("Component.index({index})"),
+            Self::Key { name } => format!("Component.Key('{name}')"),
+            Self::Index { index } => format!("Component.Index({index})"),
         }
     }
 }

src/yamltrip/_core.pyi

@@ -2,6 +2,8 @@
 
 from typing import Any, ClassVar, final
 
+from typing_extensions import override
+
 __all__ = [
     "Component",
     "Document",
@@ -22,8 +24,11 @@ class Location:
     def start(self) -> int: ...
     @property
     def end(self) -> int: ...
+    @override
     def __eq__(self, value: object, /) -> bool: ...
+    @override
     def __hash__(self) -> int: ...
+    @override
     def __repr__(self) -> str: ...
 
 @final
@@ -33,9 +38,12 @@ class FeatureKind:
     FlowMapping: ClassVar[FeatureKind]
     BlockSequence: ClassVar[FeatureKind]
     FlowSequence: ClassVar[FeatureKind]
+    @override
     def __eq__(self, value: object, /) -> bool: ...
+    @override
     def __hash__(self) -> int: ...
     def __int__(self) -> int: ...
+    @override
     def __repr__(self) -> str: ...
 
 class Component:
@@ -51,22 +59,24 @@ class Component:
         __match_args__: ClassVar[tuple[str, ...]]
         def __new__(cls, index: int) -> Component.Index: ...
         @property
-        def index(self) -> int: ...  # type: ignore[override]
+        def index(self) -> int: ...
 
-    @staticmethod
-    def key(name: str) -> Component: ...
-    @staticmethod
-    def index(index: int) -> Component: ...
+    @override
     def __eq__(self, value: object, /) -> bool: ...
+    @override
     def __hash__(self) -> int: ...
+    @override
     def __repr__(self) -> str: ...
 
 @final
 class Route:
     def __new__(cls, parts: list[str | int]) -> Route: ...
     def __len__(self) -> int: ...
+    @override
     def __eq__(self, value: object, /) -> bool: ...
+    @override
     def __hash__(self) -> int: ...
+    @override
     def __repr__(self) -> str: ...
 
 @final
@@ -79,8 +89,11 @@ class Feature:
     def kind(self) -> FeatureKind: ...
     @property
     def is_multiline(self) -> bool: ...
+    @override
     def __eq__(self, value: object, /) -> bool: ...
+    @override
     def __hash__(self) -> int: ...
+    @override
     def __repr__(self) -> str: ...
 
 @final
@@ -111,6 +124,7 @@ class Op:
     def insert_at(index: int, value: Any) -> Op: ...
     @property
     def kind(self) -> str: ...
+    @override
     def __repr__(self) -> str: ...
 
 @final