refactor(typing): Replace Any with precise types across codebase by tony · Pull Request #495 · vcs-python/vcspull

tony · 2026-01-03T13:56:01Z

Summary

This PR systematically replaces typing.Any usages with more precise types throughout the vcspull codebase, improving type safety without changing runtime behavior.

Key changes:

JSON payload types: Add TypedDict definitions (PlanEntryPayload, PlanSummaryPayload, StatusResult, RepoPayload) for CLI output structures
Config data types: Replace dict[str, Any] with dict[str, object] for raw config data, and use Mapping[str, object] for read-only inputs
Type aliases: Add domain-specific aliases like JsonValue, JsonObject, RepoConfigData, SubparserTuple
Protocols: Add _HelpTheme protocol for formatter theme typing
Generic helpers: Make update_dict use bounded TypeVar to preserve return types
Test fixtures: Tighten fixture types with explicit config structure aliases

Files modified:

Area	Files
Core	`config.py`, `_internal/config_reader.py`, `_internal/private_path.py`, `util.py`
CLI	`cli/__init__.py`, `cli/_formatter.py`, `cli/_output.py`, `cli/add.py`, `cli/discover.py`, `cli/fmt.py`, `cli/status.py`, `cli/sync.py`
Tests	`conftest.py`, `tests/test_cli.py`, `tests/cli/test_add.py`, `tests/cli/helpers.py`

Test plan

All existing tests pass (uv run pytest)
Type checking passes (uv run mypy)
Linting passes (uv run ruff check .)
Verify no runtime behavior changes by running CLI commands manually

codecov · 2026-01-03T14:22:38Z

Codecov Report

❌ Patch coverage is 85.50725% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.27%. Comparing base (e6a62d9) to head (853d89b).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
src/vcspull/cli/discover.py	50.00%	2 Missing and 2 partials ⚠️
src/vcspull/util.py	50.00%	2 Missing and 2 partials ⚠️
src/vcspull/cli/fmt.py	87.50%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #495      +/-   ##
==========================================
- Coverage   83.30%   83.27%   -0.03%     
==========================================
  Files          32       32              
  Lines        4492     4515      +23     
  Branches      903      904       +1     
==========================================
+ Hits         3742     3760      +18     
- Misses        499      502       +3     
- Partials      251      253       +2

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

tony · 2026-01-03T14:31:12Z

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

tony · 2026-01-03T14:53:13Z

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

tony · 2026-07-05T14:32:33Z

Rebased onto current master (v1.65.0). The 20-commit branch became 13 after reconciling with work that shipped since it was authored:

Dropped as superseded/obsolete:

_HelpTheme protocol — master already defines it (with a docstring).
Raw-config alias reshaping — collided with master's richer RawConfigDict TypedDict vocabulary.
typing_extensions namespace import — master eliminated typing_extensions entirely (uses the Required/Optional(total=False) split).
The two Any → object narrowings of config data (RawConfigData, config-reader returns, config helpers). These broke config-dict navigation (x in cfg, cfg[k]) across ~55 call sites, mostly tests — master deliberately keeps dynamic config values Any for ergonomic navigation. The update_repo payload-typing commits also became no-ops since master already types the param as ConfigDict.

Adapted to current master:

_output.py JSON TypedDicts converted to master's total=False split (no typing_extensions); fixed an OutputPayload alias that raised TypeError at runtime on 3.14.
SubparserTuple widened 6 → 10 (master added fmt/migrate/import/worktree).
_OrderedItem threaded through _save_ordered_items/_collapse_ordered_items_to_dict.

Net: the precise StatusResult/Plan*Payload TypedDicts, JsonValue sync events, tightened exception/parser/fmt signatures, and the _output payload types all land; the over-aggressive config-value narrowing does not. Full gate (ruff/mypy/pytest/build-docs) green.

why: Replace t.Any in create_parser returns with explicit subparser tuple typing. what: - Add SubparserTuple type alias for six CLI subparsers - Use the alias in create_parser overloads and return annotation

why: Remove unused object parameters for a clearer, specific API. what: - Narrow CouldNotGuessVCSFromURL.__init__ to repo_url only

why: Make plan/output JSON structures explicit for safer indexing and clearer contracts. what: - Introduce JsonValue aliases plus typed payloads for plan entry/summary/result - Type OutputFormatter payload handling and cast summary/status payloads - Adjust plan output tests for TypedDict iteration

why: Make status payload shape explicit and reuse it in sync plan logic/tests. what: - Define StatusResult and update status helpers to return it - Accept StatusResult in sync plan action selection - Update status/sync plan tests to build typed status inputs

why: Use object/TypedDict shapes for raw config sections without changing runtime behavior. what: - Add OrderedItem typed dict for label/section entries in add flow - Replace raw config/duplicate annotations with object-based types - Tighten discover workspace section handling with casts

why: Reduce Any usage in fixtures/helpers and align log formatter signature with stdlib. what: - Use object for doctest namespace and raw test loader return - Narrow is_valid_config input type for type guard usage - Replace LogFormatter kwargs with explicit stdlib-compatible params

why: Clarify JSON payload typing for per-repo sync events. what: - Type sync event payload dict with JsonValue entries

why: Replace Any in formatting helpers while still accepting varied config dict shapes. what: - Type normalize_repo_config/format_config with object and Mapping inputs - Update fmt tests to match new config_factory signatures

why: Preserve return type while accepting any mapping inputs safely. what: - Use MutableMapping-bounded TypeVar and Mapping input - Handle existing nested mappings with safe fallbacks

why: Make CLI test fixtures and plan helper kwargs type-safe for better mypy coverage. what: - Add explicit config structure aliases in CLI tests - Use a TypedDict for PlanEntry kwargs and a typed subprocess args alias

why: Improve type precision for JSON payload checks and config fixtures in tests. what: - Add JSON/config type aliases for CLI plan tests - Tighten fixture protocol and config writer entry types

why: Remove remaining Any usages while keeping repo sync behavior unchanged. what: - Add typed payload helpers for libvcs create_project calls - Tighten PrivatePath constructor argument types

why: Make formatter typing reflect the config shapes it actually handles. what: - Define RepoConfigData as str/path/mapping inputs - Normalize mapping inputs without redundant casts

tony force-pushed the improve-typings branch from 4663d11 to 40740bc Compare January 3, 2026 14:22

tony force-pushed the master branch from 89f4f5a to 48516d4 Compare March 25, 2026 00:01

tony force-pushed the improve-typings branch from 2d36a25 to f123f95 Compare July 5, 2026 14:32

tony added 13 commits July 5, 2026 09:57

cli/__init__(refactor[typing]): Narrow parser tuple type

bcbe610

why: Replace t.Any in create_parser returns with explicit subparser tuple typing. what: - Add SubparserTuple type alias for six CLI subparsers - Use the alias in create_parser overloads and return annotation

cli/sync(refactor[typing]): Tighten exception signature

1f710d0

why: Remove unused object parameters for a clearer, specific API. what: - Narrow CouldNotGuessVCSFromURL.__init__ to repo_url only

cli/sync(refactor[typing]): Use JsonValue for sync events

2320bea

why: Clarify JSON payload typing for per-repo sync events. what: - Type sync event payload dict with JsonValue entries

util(refactor[typing]): Make update_dict mapping-generic

df8e9ff

why: Preserve return type while accepting any mapping inputs safely. what: - Use MutableMapping-bounded TypeVar and Mapping input - Handle existing nested mappings with safe fallbacks

tests/cli(refactor[typing]): Tighten config fixture types

48db909

why: Make CLI test fixtures and plan helper kwargs type-safe for better mypy coverage. what: - Add explicit config structure aliases in CLI tests - Use a TypedDict for PlanEntry kwargs and a typed subprocess args alias

tests(refactor[typing]): Replace Any in CLI/config fixtures

227f657

why: Improve type precision for JSON payload checks and config fixtures in tests. what: - Add JSON/config type aliases for CLI plan tests - Tighten fixture protocol and config writer entry types

cli/sync(refactor[typing]): Type repo update payloads

b917a36

why: Remove remaining Any usages while keeping repo sync behavior unchanged. what: - Add typed payload helpers for libvcs create_project calls - Tighten PrivatePath constructor argument types

cli/fmt(refactor[typing]): Narrow repo config inputs

853d89b

why: Make formatter typing reflect the config shapes it actually handles. what: - Define RepoConfigData as str/path/mapping inputs - Normalize mapping inputs without redundant casts

tony force-pushed the improve-typings branch from f123f95 to 853d89b Compare July 5, 2026 15:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor(typing): Replace Any with precise types across codebase#495

refactor(typing): Replace Any with precise types across codebase#495
tony wants to merge 13 commits into
masterfrom
improve-typings

tony commented Jan 3, 2026

Uh oh!

codecov Bot commented Jan 3, 2026 •

edited

Loading

Uh oh!

tony commented Jan 3, 2026

Uh oh!

tony commented Jan 3, 2026

Uh oh!

tony commented Jul 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

tony commented Jan 3, 2026

Summary

Key changes:

Files modified:

Test plan

Uh oh!

codecov Bot commented Jan 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

tony commented Jan 3, 2026

Code review

Uh oh!

tony commented Jan 3, 2026

Code review

Uh oh!

tony commented Jul 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

codecov Bot commented Jan 3, 2026 •

edited

Loading