browser/scripts/README-strict-mode.md

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

# 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

# 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

# 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

# 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

# Get overview of migration status
npm run strict:progress

# Find all files that need migration
npm run strict:find

Testing Compliance

# 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:

   # Check current status
   node scripts/test-strict-compliance.js pattern libs/platform
   

2. After fixing strict mode violations:

   # Test compliance
   node scripts/test-strict-compliance.js pattern libs/platform
   
   # Check progress
   npm run strict:progress
   

3. Final validation:

   # 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:

node scripts/strict-mode-utils.js
node scripts/test-strict-compliance.js