mirror of
https://github.com/bitwarden/browser
synced 2026-02-06 19:53:59 +00:00
224 lines
6.2 KiB
Markdown
224 lines
6.2 KiB
Markdown
# TypeScript Strict Mode Migration Utilities
|
|
|
|
This directory contains utilities to help with the TypeScript strict mode migration process for the Bitwarden client codebase.
|
|
|
|
## Overview
|
|
|
|
The migration involves systematically enabling TypeScript strict mode across all applications and libraries. Currently, the codebase uses `typescript-strict-plugin` to allow gradual migration by excluding files with `@ts-strict-ignore` comments from strict checking.
|
|
|
|
## Utilities
|
|
|
|
### 1. Strict Mode Utils (`strict-mode-utils.js`)
|
|
|
|
A comprehensive utility for managing the strict mode migration process.
|
|
|
|
#### Commands
|
|
|
|
```bash
|
|
# Find all files with @ts-strict-ignore comments
|
|
node scripts/strict-mode-utils.js find
|
|
|
|
# Generate migration progress report
|
|
node scripts/strict-mode-utils.js progress
|
|
|
|
# Test strict mode compliance for entire codebase
|
|
node scripts/strict-mode-utils.js test
|
|
|
|
# Test strict mode compliance for specific project
|
|
node scripts/strict-mode-utils.js test libs/platform
|
|
|
|
# Check typescript-strict-plugin status
|
|
node scripts/strict-mode-utils.js plugin
|
|
```
|
|
|
|
#### NPM Scripts
|
|
|
|
```bash
|
|
# Find files with @ts-strict-ignore comments
|
|
npm run strict:find
|
|
|
|
# Generate progress report
|
|
npm run strict:progress
|
|
|
|
# Test strict mode compliance
|
|
npm run strict:test
|
|
```
|
|
|
|
### 2. Strict Compliance Tester (`test-strict-compliance.js`)
|
|
|
|
Automated testing for strict mode compliance across projects.
|
|
|
|
#### Commands
|
|
|
|
```bash
|
|
# Test all projects for strict mode compliance
|
|
node scripts/test-strict-compliance.js all
|
|
|
|
# Test projects matching a pattern
|
|
node scripts/test-strict-compliance.js pattern libs/platform
|
|
node scripts/test-strict-compliance.js pattern apps/
|
|
|
|
# Test current typescript-strict-plugin functionality
|
|
node scripts/test-strict-compliance.js plugin
|
|
```
|
|
|
|
#### NPM Scripts
|
|
|
|
```bash
|
|
# Test all projects
|
|
npm run test:strict:all
|
|
|
|
# Test typescript-strict-plugin
|
|
npm run test:strict:plugin
|
|
```
|
|
|
|
## Migration Process
|
|
|
|
### Current State
|
|
|
|
- **Total files with @ts-strict-ignore**: ~1,245 files
|
|
- **TypeScript strict plugin**: Active (version 2.4.4)
|
|
- **Base configuration**: `"strict": false` with plugin providing selective checking
|
|
|
|
### Migration Categories
|
|
|
|
The migration follows this order (as defined in the spec):
|
|
|
|
1. **Core Libraries** (`libs/platform`, `libs/common`)
|
|
2. **Domain Libraries** (`libs/auth`, `libs/vault`, etc.)
|
|
3. **UI Libraries** (`libs/components`, `libs/angular`)
|
|
4. **Applications** (`apps/cli`, `apps/browser`, `apps/desktop`, `apps/web`)
|
|
5. **Licensed Features** (`bitwarden_license/`)
|
|
|
|
### Per-Category Progress
|
|
|
|
| Category | Files with @ts-strict-ignore |
|
|
| ------------------ | ---------------------------- |
|
|
| libs/common | 381 files |
|
|
| apps/web | 239 files |
|
|
| apps/browser | 114 files |
|
|
| bitwarden_license | 115 files |
|
|
| other | 67 files |
|
|
| libs/components | 62 files |
|
|
| libs/tools | 54 files |
|
|
| libs/angular | 51 files |
|
|
| apps/cli | 45 files |
|
|
| apps/desktop | 39 files |
|
|
| libs/auth | 33 files |
|
|
| libs/vault | 28 files |
|
|
| libs/admin-console | 17 files |
|
|
|
|
## Usage Examples
|
|
|
|
### Finding Files to Migrate
|
|
|
|
```bash
|
|
# Get overview of migration status
|
|
npm run strict:progress
|
|
|
|
# Find all files that need migration
|
|
npm run strict:find
|
|
```
|
|
|
|
### Testing Compliance
|
|
|
|
```bash
|
|
# Test if a specific library is ready for strict mode
|
|
node scripts/test-strict-compliance.js pattern libs/storage
|
|
|
|
# Test all projects (warning: this will take time and likely show many failures)
|
|
npm run test:strict:all
|
|
```
|
|
|
|
### During Migration
|
|
|
|
1. **Before starting a library migration**:
|
|
|
|
```bash
|
|
# Check current status
|
|
node scripts/test-strict-compliance.js pattern libs/platform
|
|
```
|
|
|
|
2. **After fixing strict mode violations**:
|
|
|
|
```bash
|
|
# Test compliance
|
|
node scripts/test-strict-compliance.js pattern libs/platform
|
|
|
|
# Check progress
|
|
npm run strict:progress
|
|
```
|
|
|
|
3. **Final validation**:
|
|
|
|
```bash
|
|
# Test that typescript-strict-plugin still works
|
|
npm run test:strict:plugin
|
|
|
|
# Generate final report
|
|
npm run strict:progress
|
|
```
|
|
|
|
## Output Files
|
|
|
|
### `strict-compliance-report.json`
|
|
|
|
Generated by the compliance tester, contains:
|
|
|
|
- Timestamp of test run
|
|
- Summary statistics (total, passed, failed, pass rate)
|
|
- Detailed results for each project tested
|
|
- Error details for failed projects
|
|
|
|
## Integration with Existing Tools
|
|
|
|
### Existing Type Checking
|
|
|
|
The existing `npm run test:types` command runs:
|
|
|
|
- `npx tsc-strict` (typescript-strict-plugin)
|
|
- Type checking for all library tsconfig.json files
|
|
|
|
### New Strict Mode Testing
|
|
|
|
The new utilities complement existing tools by:
|
|
|
|
- Testing native TypeScript strict mode (without plugin)
|
|
- Providing detailed progress tracking
|
|
- Enabling targeted testing of specific projects
|
|
- Generating comprehensive reports
|
|
|
|
## Migration Workflow
|
|
|
|
1. **Assessment**: Use `strict:progress` to see current state
|
|
2. **Planning**: Use `strict:find` to identify files in target library
|
|
3. **Testing**: Use `test-strict-compliance.js pattern <library>` to test current compliance
|
|
4. **Implementation**: Fix strict mode violations in the library
|
|
5. **Validation**: Re-test with compliance tester
|
|
6. **Configuration**: Update library's tsconfig.json to enable strict mode
|
|
7. **Final Check**: Ensure all tests pass and plugin still works
|
|
|
|
## Notes
|
|
|
|
- The utilities create temporary tsconfig files for testing but clean them up automatically
|
|
- Failed tests include error output to help identify what needs to be fixed
|
|
- The progress report shows the current state without making any changes
|
|
- All utilities are safe to run and don't modify source code
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **"Cannot find module" errors**: Ensure you're running from the project root
|
|
2. **Permission errors**: Make sure the scripts have execute permissions
|
|
3. **TypeScript compilation errors**: These are expected during migration and indicate what needs to be fixed
|
|
|
|
### Getting Help
|
|
|
|
Run any utility without arguments to see usage information:
|
|
|
|
```bash
|
|
node scripts/strict-mode-utils.js
|
|
node scripts/test-strict-compliance.js
|
|
```
|