Principle:Wandb Weave API Migration Linting
| Knowledge Sources | |
|---|---|
| Domains | Code_Quality, Static_Analysis |
| Last Updated | 2026-02-14 10:53 GMT |
Overview
Principle of enforcing automated migration from deprecated API surfaces to their modern replacements via Concrete Syntax Tree (CST) based lint rules with auto-fix capability.
Description
API Migration Linting addresses the challenge of evolving a public API while maintaining backward compatibility during the transition period. Rather than relying on manual code review or runtime deprecation warnings, this principle uses static analysis at the syntax tree level to detect deprecated API call patterns and automatically rewrite them to their modern equivalents. CST-based analysis (via libcst) preserves formatting, comments, and whitespace during rewrites, making the changes minimally invasive. The Fixit framework provides the rule registration, test harness, and CLI integration.
Usage
Apply this principle when a project renames methods, replaces classes, or restructures its public API and needs to ensure existing code is systematically migrated. It is most effective when the deprecated and replacement APIs have a direct syntactic mapping (e.g., `client.calls()` to `client.get_calls()`, or `File(path)` to `Content.from_path(path)`).
Theoretical Basis
The mechanism follows a visitor pattern over the Concrete Syntax Tree:
- Parse: The source file is parsed into a CST that preserves all syntactic details.
- Visit: Each node of interest (e.g., `Call` nodes) is visited by the lint rule.
- Match: The visitor checks whether the node matches a deprecated API pattern (by name, qualified name, or structural shape).
- Report & Replace: If matched, the rule emits a diagnostic message and constructs a replacement CST node with the corrected API call.
Pseudo-code Logic:
# Abstract algorithm (NOT real implementation)
for node in cst.walk(source_tree):
if matches_deprecated_pattern(node):
replacement = construct_modern_equivalent(node)
report(node, message, replacement)