Annotate src/ for real: enable basedpyright type-strictness on source - #50
Merged
Conversation
Add real parameter/return/class-attribute/generic annotations to broker, reactions, config, notifier, registry_store, log_exporter, presence so they satisfy the inference-strictness rules. Annotations only; no behavior change. dict[str, Any] used for dynamic MQTT/JSON/YAML payloads; isinstance-narrowed JSON refined via documented cast().
Type the dynamic MCP/JSON dict payloads in mcp_summaries, mcp_server, and mcp_tools (list[dict[str, Any]] result accumulators, dict[str, Any] returns, class-attribute annotations). Annotations only; no behavior change.
Add ClassVar/DEFAULT_CSS annotations, compose() -> ComposeResult, event-handler param/return types, typed reactive and instance attributes across the Textual TUI widgets and screens. Annotations only; no behavior change.
Type the daemon/CLI surface: dict[str, Any] on dynamic config/JSON params, Starlette Request/WebSocket handler signatures, Callable[...] callbacks, route builder returns, and WS-adapter class attributes. Remove 14 inert mypy # type: ignore[no-untyped-def] comments (basedpyright ignores mypy codes) now that the handlers are properly annotated. Annotations only; no behavior change.
…ronment Re-enable the high-value inference-strictness rules (reportUnknown*Type, reportMissingParameterType, reportMissingTypeArgument, reportUnannotatedClassAttribute) for the shipped package via a [[tool.basedpyright.executionEnvironments]] root = "src" block, while the global block keeps them OFF so tests/, tools/, scripts/, and hatch_build.py keep their prior relaxed treatment (zero collateral). reportAny/ reportExplicitAny and reportPrivateUsage stay OFF even for src (dynamic JSON payloads; idiomatic intra-package _helper access). src now annotated to satisfy these: 0/0/0.
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
1 participant
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.
What
PR #47 reached basedpyright 0/0 by turning the inference-strictness rules OFF globally. This PR turns the high-value strictness rules back ON for the shipped package (
src/) and adds real, accurate type annotations across all ofsrc/claude_comms/until basedpyright is clean again with those rules ON. Tests, dev scripts, and the build hook stay relaxed.17 source files annotated. No runtime behavior changed; the full suite (1526 tests) still passes.
Config: which rules are ON for
src/vs OFF (and why)Rather than "strictness ON globally + disabled-in-tests" (which would have newly lit up
tools/,scripts/, andhatch_build.pywith ~535 strictness diagnostics on files outside this PR's scope), the global block keeps strictness OFF exactly as #47 shipped, and a single[[tool.basedpyright.executionEnvironments]] root = "src"re-enables the high-value rules for the package only. Net effect:src/is strict;tests/,tools/,scripts/,hatch_build.pykeep their prior, relaxed treatment with zero collateral.Turned ON for
src/:reportUnknownMemberType,reportUnknownVariableType,reportUnknownParameterType,reportUnknownArgumentType,reportUnknownLambdaTypereportMissingParameterType,reportMissingTypeArgument,reportUnannotatedClassAttributeLeft OFF (with rationale):
reportAny/reportExplicitAny— the daemon speaks dynamic JSON/dict payloads (MQTT messages, MCP tool args, YAML config) where a precise static type does not exist; forcing these would push blanket casts everywhere, strictly worse than honestAnyat the boundary. Correctness rules still flag real misuse.reportPrivateUsage— 34 legitimate intra-package accesses of module-level underscore helpers (_registry,_publish_fn,_mqtt_subscriber, ...) the maintainers documented as idiomatic; renaming all to public is churn without correctness value.reportMissingTypeStubs— 3rd-party libs (amqtt, textual, mcp, typer, rich) ship no stubs.reportImplicitOverride,reportCallInDefaultInitializer,reportUnusedCallResult,reportImplicitStringConcatenation— style, not correctness.Before / after (src/, per rule)
tests/stayed at 0/0/0 throughout.tools/+hatch_build.pyremain at their pre-existing #47 baseline (unchanged by this PR — basedpyright is not a CI gate).How it was annotated (quality)
Genuine types inferred from usage: precise where the shape is known (
dict[str, list[str]],Path,Console, textual widget classes,aiomqtt.Client, local model classes),X | NoneoverOptional, abstract types fromcollections.abc.dict[str, Any]only at genuine dynamic-JSON boundaries.Suppression count went DOWN: removed 14 inert
# type: ignore[no-untyped-def](mypy codes basedpyright ignores) now that handlers are annotated; added exactly one new# pyright: ignore[reportUnnecessaryComparison](a provably-dead defensiveis Noneguard that cannot be deleted without altering control flow). 8cast("dict[str, Any]" / "list[Any]", ...)forisinstance-narrowed dynamic JSON (pyright re-narrows annotated targets back todict[Unknown, Unknown]afterisinstance— the one genuinely unavoidable refinement), each commented inline. No real type bugs found.Gates
basedpyright src/-> 0 errors, 0 warnings, 0 notes;basedpyright tests/-> 0/0/0pytest -q-> 1526 passed (baseline), no new warningsruff check src/ tests/-> clean;ruff format --check src/ tests/-> cleanScope:
pyproject.toml+src/claude_comms/**only. Noweb/,tests/, or.sveltefiles touched.🤖 Generated with Claude Code