Repository navigation
chore(types): check the whole package with basedpyright and fix core/query errors - #130
Merged
Merged
Conversation
added 2 commits
September 7, 2026 02:06
…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
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.
This was referenced Sep 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📝 Description
CI's basedPyright step (#58) only included
src/pt_snap_cli/cli.pyand__init__.py. The core services, query engine, snapshot runtime, API, and config — over 90% of the source — were never type-checked. Running the same CI command oversrc/pt_snap_clireported 88 errors: 59 insnapshot/, 25 inquery/, 4 incore/.This PR delivers phases 1 and 2 from #122 and sets up phase 3:
Scope
include = ["src/pt_snap_cli"]— 58 files analyzed instead of 2.[[tool.basedpyright.executionEnvironments]]forsrc/pt_snap_cli/snapshotdowngrades exactly the seven rules it currently violates (reportMissingTypeArgument,reportAssignmentType,reportAttributeAccessIssue,reportUninitializedInstanceVariable,reportArgumentType,reportIndexIssue,reportImportCycles) to warnings under that root only. The same rules remain errors everywhere else — verified by dropping adef bad() -> dict:canary intosrc/pt_snap_cli/and seeing it fail with exit code 1. The comment inpyproject.tomlsays the list is meant to shrink, not grow.failOnWarnings = false. This surfaced a latent CI flake: basedpyright exits non-zero whenever any warning is present. The step only passed onmainbecause the runner's typer build is fully typed andcli.pyproduced0 warningsthere; on a developer machine with typer 0.20 the documented command already exited 1 with 34 warnings on unmodifiedmain. With the whole package included, CI reported0 errors, 845 warningsand failed (first run of this PR). The gate is now explicitly "zero errors", independent of third-party stub quality; warnings remain visible in the log as informational.Fixes for the 29 non-snapshot errors (all annotation-level; no behavior change):
query/registry.py(21 errors): the singleton declared instance attributes via annotated assignment oncls._instance._queries: dict[...] = {}, which pyright rejects. They are now class-level annotations initialized in__new__(with a targeted ignore explaining why there is deliberately no__init__).config.py/core/models.py:FocusSourceis defined once inconfig.pyandResolvedFocus.sourceuses it;core.modelsimports it instead of redeclaring. Previously a barestrfed aLiteralparameter inFocusService.resolve_focus.core/errors.py:SplitErrordeclaresphase/source_path/detailso__reduce__type-checks.core/query_service.py:list_templatesevaluatesget_query()once per row instead of twice (the second call was un-narrowable).core/split_service.py:device_tracescast islist[list[object]].query/mapper.py,query/registry.py:dictgets its type arguments.Docs:
AGENTS.mdDevelopment Commands gains the type-check command, states that the gate is zero errors, and notes the scoped relaxation.Phase 3 (not in this PR): the 59
snapshot/errors are concentrated inbase/entities.py(35) —_origin: dict = None,free_event_idx: int = None,segment_type: Literal[...] = "",DeviceSnapshotattributes assigned outside__init__. That is asnapshot/change requiring aPROVENANCE.mdentry, so it belongs in its own PR; #122 stays open to track it.🔗 Related Issue
Refs #122 (phases 1–2; phase 3 remains)
🧪 Testing
basedpyright --pythonpath <python>(CI invocation, config-driven include)0 errors, 879 warnings, exit 0, 58 filesmainwith the new include, before fixesmain, local machine (typer 0.20)0 errors, 34 warnings, exit 1 — the pre-existing flake-> dictoutsidesnapshot/)1 error, exit 1failOnWarnings=false→ exit 0pytest769 passed, 1 xfailedruff check ./black --check .pt_snap_cli.core,.config,.cli;core.models.FocusSource)✅ Checklist
Snapshot Runtime Provenance
Snapshot provenance decision: no-update
Snapshot provenance no-update reason: This PR changes pyproject.toml, AGENTS.md, and annotations in config.py, core/, and query/; no files under src/pt_snap_cli/snapshot/ are touched. The snapshot runtime's own annotation fixes are deferred to a separate PR that will carry its PROVENANCE.md entry.
📋 Additional Notes
typeCheckingMode = "standard", which switches off thereportUnknown*family; that also disables some of the rules fixed here (reportMissingTypeArgument,reportUninitializedInstanceVariable), so I kept basedpyright's default mode and made the gate explicit instead. Happy to switch if you prefer.core/query_service.pyandquery/registry.py, but in different hunks (list_templatesbody vs.get_template_infochoicesfield; singleton declaration vs. executor construction). Whichever merges second should rebase cleanly; I will resolve any conflict if one appears.