From aecd41cabd307cb00e7653e571e37323c9fb88ae Mon Sep 17 00:00:00 2001 From: codeasier Date: Mon, 7 Sep 2026 02:06:45 +0800 Subject: [PATCH 1/2] chore(types): check the whole package with basedpyright and fix core/query errors CI's basedPyright step only included cli.py and __init__.py, leaving the core services, query engine, snapshot runtime, API, and config (over 90% of the source) unchecked. Running the same command over src/pt_snap_cli reported 88 errors: 59 in snapshot/, 25 in query/, 4 in core/. Phase 1+2 of issue #122: - include = ["src/pt_snap_cli"], so every module is analyzed. - Fix the 29 non-snapshot errors. Most were the registry singleton declaring instance attributes via annotated assignment on an expression; they are now class-level annotations initialized in __new__. Also: FocusSource is defined once in config.py (ResolvedFocus.source was a bare str feeding a Literal in core.models), SplitError declares its attributes so __reduce__ type-checks, QueryService.list_templates evaluates get_query once instead of twice, split_service casts device_traces to list[list[object]], and mapper/registry give dict its type arguments. - Phase 3 (59 annotation errors in snapshot/, mostly base/entities.py) is deferred: a scoped executionEnvironment for src/pt_snap_cli/snapshot downgrades exactly the seven rules it currently violates to warnings. The same rules stay errors everywhere else, and the list is meant to shrink, not grow. Fixing snapshot/ needs its own PR with a PROVENANCE.md entry. - AGENTS.md documents the type-check command and the scoped relaxation. Result: 58 files analyzed, 0 errors (was 2 files, 0 errors). Refs #122 --- AGENTS.md | 4 ++++ pyproject.toml | 20 ++++++++++++++++---- src/pt_snap_cli/config.py | 7 +++++-- src/pt_snap_cli/core/errors.py | 4 ++++ src/pt_snap_cli/core/models.py | 3 ++- src/pt_snap_cli/core/query_service.py | 21 ++++++++++----------- src/pt_snap_cli/core/split_service.py | 2 +- src/pt_snap_cli/query/mapper.py | 8 +++++--- src/pt_snap_cli/query/registry.py | 14 ++++++++++---- 9 files changed, 57 insertions(+), 26 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6af2a90..49aadca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,10 @@ Run these commands from the repository root. - Lint: `ruff check .` - Check formatting: `black --check .` - Apply formatting: `black .` +- Type check: `python -m basedpyright --pythonpath "$(python -c 'import sys; print(sys.executable)')"` + (covers all of `src/pt_snap_cli`; `pyproject.toml` downgrades a listed set of + rules to warnings under `src/pt_snap_cli/snapshot/` until its annotations are + fixed — do not widen that list, shrink it) `tests/run_tests.sh` is tied to a developer-specific Conda path and writes coverage reports under `test_reports/`; use direct `pytest` commands unless diff --git a/pyproject.toml b/pyproject.toml index b0f5aba..830589a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -89,10 +89,22 @@ addopts = "-v --tb=short" [tool.basedpyright] pythonVersion = "3.13" -include = [ - "src/pt_snap_cli/cli.py", - "src/pt_snap_cli/__init__.py", -] +include = ["src/pt_snap_cli"] + +# The snapshot runtime was migrated from its upstream project with its original +# loose annotations (issue #122, phase 3). Only the rules it currently violates are +# downgraded, and only under this root; every other module is checked at error +# level. Remove entries here as the annotations are fixed. Changes under +# src/pt_snap_cli/snapshot/ also require a PROVENANCE.md entry. +[[tool.basedpyright.executionEnvironments]] +root = "src/pt_snap_cli/snapshot" +reportMissingTypeArgument = "warning" +reportAssignmentType = "warning" +reportAttributeAccessIssue = "warning" +reportUninitializedInstanceVariable = "warning" +reportArgumentType = "warning" +reportIndexIssue = "warning" +reportImportCycles = "warning" [tool.coverage.run] source = ["pt_snap_cli"] diff --git a/src/pt_snap_cli/config.py b/src/pt_snap_cli/config.py index b469273..32f918b 100644 --- a/src/pt_snap_cli/config.py +++ b/src/pt_snap_cli/config.py @@ -7,7 +7,7 @@ import tempfile from dataclasses import dataclass from pathlib import Path -from typing import Any +from typing import Any, Literal ENV_DB_PATH = "PT_SNAP_DB_PATH" PROJECT_FOCUS_DIR = ".pt-snap" @@ -15,6 +15,9 @@ DB_PATH_KEY = "db_path" DEVICE_ID_KEY = "device_id" +# Where a resolved database came from, in precedence order. +FocusSource = Literal["explicit", "env", "project", "global", "none"] + class FocusResolutionError(ValueError): """Raised when a configured focus cannot be read.""" @@ -27,7 +30,7 @@ class ResolvedFocus: """Resolved focus (database + optional device) with its source.""" db_path: Path | None - source: str + source: FocusSource focus_file: Path | None = None device_id: int | None = None diff --git a/src/pt_snap_cli/core/errors.py b/src/pt_snap_cli/core/errors.py index 22053bd..31b974f 100644 --- a/src/pt_snap_cli/core/errors.py +++ b/src/pt_snap_cli/core/errors.py @@ -101,6 +101,10 @@ class SourceChangedError(ImportExecutionError): class SplitError(PtSnapCoreError): """A phase-identifying split failure suitable for CLI presentation.""" + phase: SplitPhase + source_path: Path + detail: str + def __init__(self, phase: SplitPhase, source_path: Path, detail: str) -> None: self.phase = phase self.source_path = source_path diff --git a/src/pt_snap_cli/core/models.py b/src/pt_snap_cli/core/models.py index d9d0c48..f3231cd 100644 --- a/src/pt_snap_cli/core/models.py +++ b/src/pt_snap_cli/core/models.py @@ -4,7 +4,8 @@ from pathlib import Path from typing import Any, Literal -FocusSource = Literal["explicit", "env", "project", "global", "none"] +from pt_snap_cli.config import FocusSource + CacheMissReason = Literal[ "database_missing", "database_invalid", diff --git a/src/pt_snap_cli/core/query_service.py b/src/pt_snap_cli/core/query_service.py index c23f654..b4a2e95 100644 --- a/src/pt_snap_cli/core/query_service.py +++ b/src/pt_snap_cli/core/query_service.py @@ -72,18 +72,17 @@ def list_templates( if category is not None else list_queries_with_details() ) - return [ - TemplateSummary( - name=row["name"], - description=row["description"], - category=( - get_query(row["name"]).category - if get_query(row["name"]) is not None - else category - ), + summaries: list[TemplateSummary] = [] + for row in template_rows: + template = get_query(row["name"]) + summaries.append( + TemplateSummary( + name=row["name"], + description=row["description"], + category=template.category if template is not None else category, + ) ) - for row in template_rows - ] + return summaries def get_template_info(self, name: str) -> TemplateInfo: template = get_query(name) diff --git a/src/pt_snap_cli/core/split_service.py b/src/pt_snap_cli/core/split_service.py index 520043a..ba8287b 100644 --- a/src/pt_snap_cli/core/split_service.py +++ b/src/pt_snap_cli/core/split_service.py @@ -138,7 +138,7 @@ def _slice_device( try: raw_dir = stage / f".device-{device}" raw_dir.mkdir() - event_count = len(cast(list[object], representation["device_traces"])[device]) + event_count = len(cast(list[list[object]], representation["device_traces"])[device]) hooker = SliceDumpHooker( dump_dir=str(raw_dir), num_of_slices=slices if slices is not None else 1, diff --git a/src/pt_snap_cli/query/mapper.py b/src/pt_snap_cli/query/mapper.py index a9f2cf8..d02c802 100644 --- a/src/pt_snap_cli/query/mapper.py +++ b/src/pt_snap_cli/query/mapper.py @@ -20,7 +20,7 @@ def __init__(self): "hex": lambda x: hex(x) if isinstance(x, int) else x, "datetime": lambda x: x, } - self._model_factories: dict[str, Callable[[dict], Any]] = {} + self._model_factories: dict[str, Callable[[dict[str, Any]], Any]] = {} def register_type_converter(self, type_name: str, converter: Callable[[Any], Any]) -> None: """Register a type converter. @@ -31,7 +31,9 @@ def register_type_converter(self, type_name: str, converter: Callable[[Any], Any """ self._type_converters[type_name] = converter - def register_model_factory(self, model_name: str, factory: Callable[[dict], Any]) -> None: + def register_model_factory( + self, model_name: str, factory: Callable[[dict[str, Any]], Any] + ) -> None: """Register a model factory. Args: @@ -179,7 +181,7 @@ def register_type_converter( def register_model_factory( model_name: str, - factory: Callable[[dict], Any], + factory: Callable[[dict[str, Any]], Any], ) -> None: """Register a model factory with default mapper. diff --git a/src/pt_snap_cli/query/registry.py b/src/pt_snap_cli/query/registry.py index 7671d64..b0662bc 100644 --- a/src/pt_snap_cli/query/registry.py +++ b/src/pt_snap_cli/query/registry.py @@ -5,6 +5,7 @@ import warnings from collections.abc import Callable from pathlib import Path +from typing import Any from pt_snap_cli.query.config import QueryConfig, QueryTemplate @@ -15,13 +16,18 @@ class QueryRegistry: """Registry for predefined query templates.""" _instance: QueryRegistry | None = None + # Initialized in __new__ (the singleton has no __init__ so repeated + # QueryRegistry() calls cannot wipe the shared state). + _queries: dict[str, QueryTemplate] # pyright: ignore[reportUninitializedInstanceVariable] + _factories: dict[str, QueryFactory] # pyright: ignore[reportUninitializedInstanceVariable] def __new__(cls) -> QueryRegistry: """Singleton pattern for global registry.""" if cls._instance is None: - cls._instance = super().__new__(cls) - cls._instance._queries: dict[str, QueryTemplate] = {} - cls._instance._factories: dict[str, QueryFactory] = {} + instance = super().__new__(cls) + instance._queries = {} + instance._factories = {} + cls._instance = instance return cls._instance @classmethod @@ -175,7 +181,7 @@ def get_query(name: str) -> QueryTemplate | None: return _registry.get(name) -def get_template_info(name: str) -> dict | None: +def get_template_info(name: str) -> dict[str, Any] | None: """Get detailed information about a template. Args: From 85c53b637cdba45293ea94741cb5b0d857bd5604 Mon Sep 17 00:00:00 2001 From: codeasier Date: Mon, 7 Sep 2026 02:13:09 +0800 Subject: [PATCH 2/2] chore(types): gate basedpyright on errors only basedpyright exits non-zero whenever warnings are present unless failOnWarnings is false. The CI step only passed on main because the runner's typer build is fully typed and cli.py produced zero warnings there; on developer machines with an older typer the same command already exited 1 with 34 warnings. Including the whole package raises the count to several hundred reportUnknown* warnings and fails CI. Set failOnWarnings = false so the gate is "no errors" regardless of third-party stub quality, and say so in AGENTS.md. --- AGENTS.md | 7 ++++--- pyproject.toml | 5 +++++ 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 49aadca..bcb5222 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,9 +22,10 @@ Run these commands from the repository root. - Check formatting: `black --check .` - Apply formatting: `black .` - Type check: `python -m basedpyright --pythonpath "$(python -c 'import sys; print(sys.executable)')"` - (covers all of `src/pt_snap_cli`; `pyproject.toml` downgrades a listed set of - rules to warnings under `src/pt_snap_cli/snapshot/` until its annotations are - fixed — do not widen that list, shrink it) + (covers all of `src/pt_snap_cli`; the gate is zero errors and warnings are + informational. `pyproject.toml` downgrades a listed set of rules to warnings + under `src/pt_snap_cli/snapshot/` until its annotations are fixed — do not + widen that list, shrink it) `tests/run_tests.sh` is tied to a developer-specific Conda path and writes coverage reports under `test_reports/`; use direct `pytest` commands unless diff --git a/pyproject.toml b/pyproject.toml index 830589a..d654469 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -90,6 +90,11 @@ addopts = "-v --tb=short" [tool.basedpyright] pythonVersion = "3.13" include = ["src/pt_snap_cli"] +# basedpyright exits non-zero on warnings by default. The gate is "no errors"; +# warnings (mostly reportUnknown* noise from third-party stubs) are informational. +# Without this, the result depends on how well-typed the installed typer happens +# to be, which is why the check passed in CI yet failed on developer machines. +failOnWarnings = false # The snapshot runtime was migrated from its upstream project with its original # loose annotations (issue #122, phase 3). Only the rules it currently violates are