deprecated-api-updater

# Deprecated API Updater

Identify and replace deprecated API usage with modern alternatives automatically.

## Quick Start

### Detect Deprecated APIs

Scan code to identify deprecated API usage:

```bash
# Scan a single file
python scripts/detect_deprecated_apis.py src/app.py

# Scan entire directory
python scripts/detect_deprecated_apis.py src/

# Specify language explicitly
python scripts/detect_deprecated_apis.py legacy/ --language python

# Output as JSON
python scripts/detect_deprecated_apis.py src/ --format json
```

### Replace Deprecated APIs

Automatically replace deprecated APIs:

```bash
# Dry run (preview changes)
python scripts/replace_deprecated_apis.py src/ --dry-run

# Apply replacements (creates .bak backups)
python scripts/replace_deprecated_apis.py src/

# Replace in specific language
python scripts/replace_deprecated_apis.py src/ --language javascript
```

## Supported Languages

### Python
- Standard library (collections, time, os, platform, imp)
- Django (URL routing, encoding, translation, models)
- Flask (JSON handling, send_file)
- SQLAlchemy, Pandas, NumPy, Requests

See **[python_deprecations.md](references/python_deprecations.md)** for complete reference.

### JavaScript/TypeScript
- Node.js core (Buffer, url, crypto, fs, util)
- React (lifecycle methods, createClass, PropTypes, Context)
- Express.js (body-parser)
- Webpack, Moment.js alternatives

See **[javascript_deprecations.md](references/javascript_deprecations.md)** for complete reference.

### Java
- Java core (Date/Calendar, Thread methods, finalize)
- Spring Framework (WebMvcConfigurerAdapter, RestTemplate)
- Hibernate (Criteria API)
- JUnit 4 → JUnit 5
- Android (AsyncTask, ProgressDialog, startActivityForResult)

See **[java_deprecations.md](references/java_deprecations.md)** for complete reference.

### Other Languages
- Ruby: URI.escape, Dir.exists?, File.exists?
- Go: ioutil package functions

## Detection Methods

### AST-Based Detection (Precise)

For Python and JavaScript, the skill uses Abstract Syntax Tree parsing for accurate detection:

- **Advantages**: Precise, understands code structure, fewer false positives
- **Limitations**: Requires parseable code, language-specific implementation

**Example**: Detects `os.popen()` by analyzing the AST node structure, not just string matching.

### Pattern Matching (Fast)

For all languages, regex-based pattern matching provides fast detection:

- **Advantages**: Works across all languages, fast, handles unparseable code
- **Limitations**: May have false positives, less precise

**Both methods are used together** for comprehensive detection.

## Workflow

### 1. Scan for Deprecations

Run detection to identify deprecated APIs:

```bash
python scripts/detect_deprecated_apis.py src/
```

**Output example**:
```
Found 3 deprecated API usage(s):

📍 src/utils.py:5:0
   Deprecated: collections.Mapping
   Replacement: collections.abc.Mapping
   Context: from collections import Mapping
   Detection: ast

📍 src/legacy.py:12:9
   Deprecated: os.popen()
   Replacement: subprocess.run() or subprocess.Popen()
   Context: result = os.popen('ls')
   Detection: ast
```

### 2. Review Suggestions

Examine the detected deprecations and suggested replacements. Check the reference documentation for detailed migration guides.

### 3. Test Replacements (Dry Run)

Preview changes before applying:

```bash
python scripts/replace_deprecated_apis.py src/ --dry-run
```

**Output shows**:
- What will be replaced
- Line-by-line changes
- Deprecated API → Replacement API mapping

### 4. Apply Replacements

Apply changes with automatic backups:

```bash
python scripts/replace_deprecated_apis.py src/
```

**Creates**:
- `.bak` backup files for all modified files
- Updated source files with modern APIs

### 5. Validate Changes

**Critical**: Always validate after replacement:

```bash
# Run tests
npm test  # JavaScript
pytest    # Python
mvn test  # Java

# Run linters
eslint src/     # JavaScript
flake8 src/     # Python
mvn checkstyle  # Java

# Manual testing
# Test critical functionality
```

### 6. Commit Changes

Once validated:

```bash
# Review changes
git diff

# Commit
git add .
git commit -m "Replace deprecated APIs with modern alternatives"

# Remove backup files
find . -name "*.bak" -delete
```

## Best Practices

### Before Replacement

1. **Create a branch**: `git checkout -b fix/deprecated-apis`
2. **Commit current state**: Ensure working directory is clean
3. **Run tests**: Verify tests pass before changes
4. **Review deprecation docs**: Check reference files for context

### During Replacement

1. **Start with dry run**: Always preview changes first
2. **Replace incrementally**: Process one module/directory at a time
3. **Keep backups**: Don't delete `.bak` files until validated
4. **Check imports**: Some replacements require new imports

### After Replacement

1. **Run full test suite**: Catch any breaking changes
2. **Check build output**: Look for new warnings
3. **Manual testing**: Test critical user flows
4. **Update dependencies**: Install any newly required packages
5. **Code review**: Have team members review changes

## Common Scenarios

### Scenario 1: Upgrading Django 2.x → 3.x

**Deprecations**:
- `django.conf.urls.url` → `django.urls.path`
- `force_text()` → `force_str()`
- `ugettext` → `gettext`

**Process**:
```bash
# Detect Django-specific deprecations
python scripts/detect_deprecated_apis.py myproject/ --language python

# Preview replacements
python scripts/replace_deprecated_apis.py myproject/ --dry-run

# Apply
python scripts/replace_deprecated_apis.py myproject/

# Test
python manage.py test
```

### Scenario 2: Upgrading React 17 → 18

**Deprecations**:
- `ReactDOM.render()` → `ReactDOM.createRoot()`
- Unsafe lifecycle methods → Modern alternatives

**Process**:
```bash
# Detect React deprecations
python scripts/detect_deprecated_apis.py src/ --language javascript

# Manual review needed for complex cases
# Some React upgrades require s