Phase 4: Normalize codebase for shared package extraction

[edvilme]

Overview

Phase 4 normalization for isort as part of the shared package extraction effort.

Tracking issue: microsoft/vscode-python-tools-extension-template#290

What is normalization?

All 5 Python tool extensions (black-formatter, flake8, isort, mypy, pylint) were originally scaffolded from the same template and share ~70% of their code. Over time, each repo diverged: functions were renamed, parameters changed, utilities landed in different files, and features were added to some repos but not others.

Normalization is the process of re-aligning these codebases so that:

1. Equivalent functions have identical signatures — e.g., normalize_path() should accept the same parameters everywhere
2. Equivalent functionality lives in the same file — e.g., if _get_settings_by_path() exists in 4 repos' lsp_server.py, the 5th repo should have it too
3. Missing shared features are backported — e.g., localization files that exist in 3 repos should be added to the other 2

Why is this needed?

The end goal (template#290) is to extract the shared code into a reusable package (vscode-python-tool-lsp). For this to work, we need a clean 1:1 mapping between repo code and package code. If function signatures differ or utilities live in different files, extraction becomes a messy per-repo special case instead of a clean "delete shared file, import from package" operation.

All changes are backwards-compatible — adding optional parameters with defaults, aligning function signatures, and moving code to the correct files. No behavioral changes.

Tasks

Structural Alignment (methods in the right files)

• 4.S1 Add update_environ_path() to lsp_server.py (currently missing)
• 4.S3 Align _log_version_info() — remove settings parameter to match other repos

Python Normalizations (bundled/tool/)

• 4.2c Align lsp_jsonrpc.py — change Exception to ConnectionError in RPC error handling
• 4.2d Add resolve_symlinks=True parameter to normalize_path() in lsp_utils.py
• 4.2e Add is_match(patterns, file_path, workspace_root=None) to lsp_utils.py (currently missing)
• 4.2f Add exit_code=None field to RunResult dataclass in lsp_utils.py
• 4.2g Investigate lsp_runner.py os.getcwd() in sys.path — align or document

TypeScript Normalizations (src/common/)

• 4.0f Move expandTilde() export from settings.ts to envFile.ts
• 4.1b Align getDocumentSelector() — add notebook scheme support (or parameterize)
• 4.1d Upgrade configWatcher.ts to robust disposal pattern (error handling + disposed flag)
• 4.1e Align settings.ts to base ISettings interface with shared fields
• 4.1f Parameterize server.ts via ToolConfig.hooks interface
• 4.1g Converge extension.ts to thin wrapper (depends on 4.1e + 4.1f)

Feature Parity

None — isort already has full feature parity.

PR Strategy

Each task gets its own branch and PR for focused review:

• Branch naming: phase4/<task-slug>
• All changes are backwards-compatible
• Tests must pass before merge