Skip to content

[S9b] Audit consumer API compatibility at reviewed revisions - #162

Closed
Eduardo Villalpando Mello (edvilme) wants to merge 1 commit into
mainfrom
refactor/s9-api-compatibility
Closed

Eduardo Villalpando Mello (edvilme) wants to merge 1 commit into
mainfrom
refactor/s9-api-compatibility

Conversation

@edvilme

Copy link
Copy Markdown
Contributor

Summary

  • Record exact, immutable S8 consumer revisions for Black, Flake8, isort, mypy and Pylint, all using shared revision 89cb5fc78d32dbdf5eb7d38d2b2bd78f0e6798a2.
  • Audit actual TypeScript imports/activation/settings/hooks and Python facade/configuration/execution/adapters, distinguishing runtime use from re-exports, separately launched runners, tests and dynamic loaders.
  • Preserve isort's active manual lifecycle and mypy's daemon/lower-level execution needs. No deprecation is justified by this finite evidence, so no annotations or API changes are manufactured.
  • Link the contributor-facing audit from CONTRIBUTING.

Refs #159 (S9b; independent of the S9a documentation PR #161). This PR is based directly on main and does not close the two-part issue automatically.

Validation

  • git diff --cached --check passed.
  • Verified 4 local documentation links/anchors, 27 reference-link uses and 32 immutable source links/line ranges against the reviewed Git objects.
  • Rechecked all five consumer HEADs, gitlinks, clean states, actual legacy ToolConfig definitions and ToolServer construction. Inspected packaging/test/build entrypoints without changing or rebuilding consumers.
  • Documentation-only: no runtime tests required, no dedicated Markdown checker configured, and no new tooling/dependencies installed.

Compatibility

No removals, narrowed re-exports, changed signatures, warnings, defaults or runtime behavior. Lower-level public APIs remain supported; private _settings/_routing remain implementation details. No dependency upgrades, layout moves, lifecycle rewrites or deferred S4 changes. No S9a file dependency or PR stack is needed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 85ef72cc-9e26-4bc4-b1c3-55256d9bef91
@edvilme Eduardo Villalpando Mello (edvilme) added debt Code Cleanup, Refactorings and Repo health. Not feature related documentation Improvements or additions to documentation labels Nov 17, 2026
@bschnurr

Copy link
Copy Markdown
Member

🔒 Automated review in progress — Bill Schnurr (@bschnurr) is auto-reviewing this PR.

@bschnurr

Copy link
Copy Markdown
Member

Reviewed commit: e766d4cc27c76add10db44fff4763c1f41a19501

Result: 🔴 could-not-verify

Verification details

Verification: Automated verification is best effort. The PR author remains responsible for testing.

Summary: [unavailable] Container verification could not start and local execution was not authorized for this PR HEAD: C:\Program Files\RedHat\Podman\podman.EXE --connection pyrx-automation failed: stderr: Error: unable to start container "260676886c647c418a9301813a1cb857b23da8f5bee445d3352c9a63a21b92fc": crun: open `memory.max` for writing: No such file or directory: OCI runtime attempted to invoke a command that was not found

Test runs: none recorded.

@bschnurr Bill Schnurr (bschnurr) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved via Review Center.

@bschnurr Bill Schnurr (bschnurr) added the review-auto:approved Automated review: no blocking findings (approval posted). label Nov 17, 2026
@edvilme

Copy link
Copy Markdown
Contributor Author

Disposition: retain this audit as review evidence, not repository documentation.

Per maintainer direction, this PR will be closed without merging. The five-consumer audit found no justified deprecations. #161 contains the durable supported-API guidance; no runtime changes are needed. Nothing is being merged as part of this disposition.

The complete report from commit e766d4cc27c76add10db44fff4763c1f41a19501 is preserved below so the evidence does not depend on merging or retaining a branch.

Complete revision-linked compatibility audit

Consumer compatibility audit (S9)

This is a source audit for S9,
reviewed on 2026-11-17. It records observed imports, composition and ownership,
not a census of every possible caller or a new runtime validation result.
No shared entry point is sufficiently demonstrated to be superseded; no
deprecation annotations or runtime changes are introduced.

Reviewed revisions and method

Consumer Exact reviewed commit S8 adoption PR
Black 56828c28d96c85297fc3b5a6b2a0bf32afa44f9e #851
Flake8 5cbebad763b1f551d358894e6cda39c4eca8f8e0 #625
isort 3246eb1b504b64a43f240146bf06e95321364eda #806
mypy 35ff9df1d9d7bbfa132746ba602e01aa5dc37514 #669
Pylint f83e7b3dd8806aa443bf6e801222263021278a07 #933

All five gitlinks and checked-out shared submodules were
89cb5fc78d32dbdf5eb7d38d2b2bd78f0e6798a2.
The consumer checkouts were clean and at the revisions above. Inspection used
immutable Git objects, not generated bundles or potentially changing worktree
files; no consumer or submodule was edited or rebuilt.

The audit followed shared imports through src/extension.ts, tool definitions
and local settings/status/runner adapters, then Python server handlers,
configuration, execution and compatibility wrappers. Build/install entry points,
tests, re-exports and dynamic test loaders were considered separately. Missing
direct imports do not establish lack of use: helpers are also reached through
shared composition, local adapters and separately launched runner scripts.

TypeScript: observed imports and use

The runtime source imports the source-relative typescript/dist public entry
point. All five import ToolConfig, IBaseSettings, loadServerDefaults,
getConfiguration and getWorkspaceFolders. The configurations are explicitly
annotated ToolConfig, not ToolDefinition<TSettings>: the typed definition is
an available opt-in, not an already-completed migration.

Consumer evidence Activation and additional shared imports
Black client, configuration/settings activateToolExtension, ToolExtensionRuntime; logLegacySettings (locally aliased), traceInfo, traceWarn. Activation passes the configured tool, retains default-formatter/legacy-setting logging and awaits runtime deactivation.
Flake8 client, configuration/settings activateToolExtension, ToolExtensionRuntime, resolveExtensionRoot, aliased logLegacySettings, traceWarn. Tool-specific legacy-setting messages remain local.
isort client, configuration/settings/runner createToolContext, ToolExtensionContext, deactivateServer, PythonEnvironmentsProvider, registerCommonSubscriptions, registerLogger, traceError; local execution additionally uses expandTilde, aliased getWorkspaceSettings, getEnvFileVars, getProjectRoot, getWorkspaceFolder, getDocumentSelector, traceLog and traceWarn.
mypy client, configuration/settings activateToolExtension, ToolExtensionRuntime, resolveExtensionRoot, aliased logLegacySettings, traceWarn. Activation retains its legacy-setting logging and awaits runtime deactivation.
Pylint client, configuration/settings/status activateToolExtension, ToolExtensionRuntime, resolveExtensionRoot, aliased logLegacySettings, traceWarn, onDidChangeConfiguration; score UI imports createLanguageStatusItem, createStatusBarItem, getDocumentSelector and onDidChangeActiveTextEditor. The retained combined status-registration helper and the active score-only path are distinct.

Extension policy is still configuration, not shared machinery

The linked src/common/constants.ts definitions retain these custom settings
and capabilities:

  • Black: serverTransport, with isFormatter: true; local settings code
    retains transport selection and formatter guidance.
  • Flake8: enabled, severity, ignorePatterns, extraPaths.
  • isort: check, severity, extraPaths; serverEnabled is tracked for
    restarts but is not a custom settings-payload key.
  • mypy: ignorePatterns, extraPaths, reportingScope, preferDaemon,
    daemonStatusFile, severity; supportsPerProjectEnvironments: true.
  • Pylint: enabled, severity, ignorePatterns, lintOnChange;
    refreshExtensionOnPackagesChange: true.

Pylint supplies both launch hooks in its linked client:
getLaunchEnvironment reads the unscoped pylint.lintOnChange configuration to
set/remove VSCODE_PYLINT_LINT_ON_CHANGE; configureClient registers
pylint/score, pylint/lintingStarted and pylint/lintingFailed handlers with
registerDisposable. The runtime owns those per-client registrations.
Pylint still owns its score UI and visibility listener through
context.subscriptions. This is evidence for the hook boundary, not a reason to
move UI policy into shared activation or hooks into serialized settings.

isort needs manual composition

In src/extension.ts lines 30–84, isort owns the output/logger and
Python provider, creates a tool context, and overrides runServer to switch
between LSP and local sort-import features when serverEnabled changes. It wires
common subscriptions, defers initialization and calls deactivateServer after
local-feature cleanup.

Its linked settings.ts wraps shared getWorkspaceSettings with
python.sortImports.args/path legacy fallbacks. runner.ts uses that wrapper,
workspace/root resolution and getEnvFileVars for local execution;
sortImports.ts registers local code actions using getDocumentSelector.
The activation facade does not replace this composition without changing
isort-specific lifecycle policy. Those lower-level APIs remain supported.

Python: observed facade and lower-level usage

All five construct ToolServer(ToolServerConfig(...), server=LSP_SERVER), keeping
their own pygls server and LSP handlers. All use document settings, CWD and facade
logging. Their server modules import RunResult and update_environ_path;
local lsp_utils.py adapters import classify_python_file.

Consumer evidence Settings, execution and lifecycle actually retained
Black server, adapters Root imports of ToolServer/ToolServerConfig; apply_settings, log_startup_info, global defaults, execute_tool, handle_shutdown/handle_exit. Formatting keeps match_line_endings, strip_trailing_newline and interpreter-based mode selection.
Flake8 server, adapters Imports the facade from the public server module; initialization updates global_settings then calls update_workspace_settings, retaining extra-path setup and version logging. Uses global defaults, execute_tool, shutdown/exit helpers, is_current_interpreter, is_match and QuickFixRegistrationError. Classification adapters distinguish PythonFileKind values.
isort server, adapters Imports the facade from server; initialization updates globals/workspaces and calls get_settings_by_path for extra paths. Uses global defaults, execute_tool, shutdown/exit helpers and is_current_interpreter; environment construction and import-sort policy remain local.
mypy server, adapters Root facade imports; apply_settings, log_startup_info, global defaults, workspace updates, path/document lookup and get_document_key. Execution uses local utils.run_path, delegating to shared run_path, rather than execute_tool. Its adapter merges partial environments and calls shared is_same_path with symlink resolution. is_match/normalize_path, nearest-config CWD policy and daemon stop/kill handlers remain in use.
Pylint server, adapters Root facade imports; apply_settings, log_startup_info, path/document lookup, execute_tool, shutdown/exit helpers, is_current_interpreter, is_match and QuickFixRegistrationError. Configuration keeps default_settings for enabled/severity/extra paths and hardcoded_settings={"ignorePatterns": []} for global defaults; workspace ignore patterns remain client-resolved.

Black, Flake8, isort and mypy retain module-level WORKSPACE_SETTINGS and
GLOBAL_SETTINGS aliases to the facade dictionaries. Initialization, version
bookkeeping and mypy daemon cleanup also access that state. Replacing the
dictionaries or hiding their mutation behind new mandatory setters would not be
a documentation-only compatibility change.

Flake8/isort's manual settings application and the retained _get_*/get_cwd
wrappers are extension-local entry points, not competing new shared APIs.
Their presence does not justify removing shared facade methods or rewriting
consumer handlers.

Runner scripts and compatibility re-exports matter

Black, Flake8, isort and Pylint retain the following in their linked adapters:

  • lsp_runner.py imports JsonRpc, RunResult, run_message_loop and
    run_module, then runs run_message_loop(RPC, run_module, RunResult).
    These are actual separately launched entry points, not dead imports merely
    because lsp_server.py uses execute_tool.
  • lsp_jsonrpc.py imports/re-exports JsonRpc, RpcRunResult,
    StreamClosedException, shutdown_json_rpc, and wraps
    get_or_start_json_rpc/run_over_json_rpc with its local runner-script path.
    Retained wrapper exports are compatibility evidence, not proof that every
    exported name is invoked by each current server.
  • lsp_notebook.py retains MAGIC_LINE_RE, NOTEBOOK_SYNC_OPTIONS,
    CellOffset, SyntheticDocument, TextDocumentLike, build_notebook_source,
    get_cell_for_line and remap_diagnostics_to_cells imports/re-exports.
    All four servers use notebook sync options; Flake8/Pylint also call notebook
    construction/remapping helpers.

Black's lsp_utils.py also preserves run_module/run_path wrappers, including
its compatibility timeout argument. mypy's active run_path wrapper and daemon
cleanup independently show why recommending ToolServer cannot deprecate
lower-level execution helpers.

Separate test/build observations from runtime adoption

  • All five environment-file unit tests import getEnvFileVars; mypy's
    constants.unit.test.ts additionally imports getWorkspaceSettings.
    These supplement, not replace, isort's runtime usage.
  • All five test_change_cwd.py files import SERVER_CWD and change_cwd.
    Flake8's stdlib test also imports paths and
    reset_caches; its notebook test imports
    MAX_LSP_CHARACTER from the public notebook module, not the package root.
  • Black, Flake8 and mypy
    CommonJS/VM tests intercept the shared entry with test doubles. Pylint's
    lifecycle test also loads built dist/server.js with mocked
    collaborators to exercise launch behavior. That test-only deep load does not
    establish a recommended extension-runtime import path.
  • Consumer package.json/build scripts build the pinned shared TypeScript
    source before extension compilation; each noxfile.py installs Python from
    the pinned checkout into bundled/libs. Packaging tests check the shared
    import and local-install metadata. These build/diagnostic distribution names
    are not npm/PyPI consumption APIs. This audit did not rebuild artifacts or
    claim to solve deferred build-provenance work.

Compatibility decisions and replacement guidance

Surface considered Decision from this evidence
ToolConfig / IBaseSettings Keep supported: all five import them. Recommend optional ToolDefinition<TSettings> / ToolSettings<TSettings> for stronger custom-setting types, not a mandatory or deprecated migration.
createToolContext, registerCommonSubscriptions, deactivateServer, provider/logging/settings helpers Keep supported: isort's active manual lifecycle and local mode need them. Recommend activateToolExtension only where its ownership fits.
restartServer / createServer Keep supported: shared activation composes these internally, and launch tests exercise that machinery. Lack of a direct import in these five runtime entry points is not evidence that these exports are unused or safely replaceable.
ToolServer settings methods and writable dictionaries Keep the public facade and existing aliases. _settings/_routing are private stateless collaborators, not replacements or consumer customization points. No reviewed consumer imports them. Preserve shallow construction, in-place updates and distinct path/document fallbacks.
Python runner, JSON-RPC, notebook and path helpers Keep supported: direct runner entry points, adapters and mypy's execution path remain evidence of lower-level use. A facade recommendation does not supersede these operations.
Legacy-setting logging and local compatibility wrappers No shared deprecation: logLegacySettings is actively called. Messages about obsolete user settings do not deprecate the logging helper, and extension-local wrapper changes require their own caller evidence.

Use the existing typed definition,
activation and
hook guidance where applicable;
keep Python settings/routing access through ToolServer. None is a universal
drop-in replacement for the lower-level surfaces above.

Future deprecation proposals need revision-linked call-site evidence, a
behaviorally suitable replacement and a plan preserving existing callers,
including adapters, tests and manual lifecycles. This five-consumer snapshot
cannot establish absence of other callers. No exports, signatures, warnings,
defaults, dependencies or runtime behavior change as a result of this audit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

debt Code Cleanup, Refactorings and Repo health. Not feature related documentation Improvements or additions to documentation review-auto:approved Automated review: no blocking findings (approval posted).

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants