Skip to content

chore(types): check the whole package with basedpyright and fix core/query errors - #130

Merged
codeasier merged 2 commits into
mainfrom
chore/issue-122-basedpyright-scope
Sep 17, 2026
Merged

codeasier merged 2 commits into
mainfrom
chore/issue-122-basedpyright-scope

Conversation

@codeasier

@codeasier codeasier commented Sep 6, 2026 •

Copy link
Copy Markdown
Owner

📝 Description

CI's basedPyright step (#58) only included src/pt_snap_cli/cli.py and __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 over src/pt_snap_cli reported 88 errors: 59 in snapshot/, 25 in query/, 4 in core/.

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.
  • A scoped [[tool.basedpyright.executionEnvironments]] for src/pt_snap_cli/snapshot downgrades 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 a def bad() -> dict: canary into src/pt_snap_cli/ and seeing it fail with exit code 1. The comment in pyproject.toml says 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 on main because the runner's typer build is fully typed and cli.py produced 0 warnings there; on a developer machine with typer 0.20 the documented command already exited 1 with 34 warnings on unmodified main. With the whole package included, CI reported 0 errors, 845 warnings and 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 on cls._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: FocusSource is defined once in config.py and ResolvedFocus.source uses it; core.models imports it instead of redeclaring. Previously a bare str fed a Literal parameter in FocusService.resolve_focus.
  • core/errors.py: SplitError declares phase/source_path/detail so __reduce__ type-checks.
  • core/query_service.py: list_templates evaluates get_query() once per row instead of twice (the second call was un-narrowable).
  • core/split_service.py: device_traces cast is list[list[object]].
  • query/mapper.py, query/registry.py: dict gets its type arguments.

Docs: AGENTS.md Development 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 in base/entities.py (35) — _origin: dict = None, free_event_idx: int = None, segment_type: Literal[...] = "", DeviceSnapshot attributes assigned outside __init__. That is a snapshot/ change requiring a PROVENANCE.md entry, so it belongs in its own PR; #122 stays open to track it.

🔗 Related Issue

Refs #122 (phases 1–2; phase 3 remains)

🧪 Testing

  • Tests added/updated — not applicable (type annotations and tool configuration; existing suite covers the touched code paths)
  • Manual testing completed
Check Result
basedpyright --pythonpath <python> (CI invocation, config-driven include) 0 errors, 879 warnings, exit 0, 58 files
Same command on main with the new include, before fixes 88 errors
Same command on unmodified main, local machine (typer 0.20) 0 errors, 34 warnings, exit 1 — the pre-existing flake
Scoping canary (-> dict outside snapshot/) 1 error, exit 1
Minimal repro of the default: one file with a warning default → exit 1; failOnWarnings=false → exit 0
pytest 769 passed, 1 xfailed
ruff check . / black --check . clean
Import smoke (pt_snap_cli.core, .config, .cli; core.models.FocusSource) ok, no cycle

✅ Checklist

  • Code follows project guidelines
  • Documentation updated (if applicable)
  • No new warnings introduced
  • Changes tested locally

Snapshot Runtime Provenance

  • Snapshot provenance evaluation completed when snapshot runtime files change
    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

codeasier 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.
@codeasier
codeasier merged commit 380dcf9 into main Sep 17, 2026
8 of 12 checks passed
@codeasier
codeasier deleted the chore/issue-122-basedpyright-scope branch October 3, 2026 19:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant