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

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,15 @@ 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]
+        require_serial: true
   - repo: https://github.com/jendrikseipp/vulture
     rev: v2.16
     hooks:

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",
@@ -77,6 +80,26 @@ report.exclude_also = [
 ]
 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 = [

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