npm package: @siteone/ts-migration-tool
Description: TypeScript migration enforcement toolkit with customizable checks and file providers
Author: SiteOne s.r.o.
Latest version: 0.2.2

# @siteone/ts-migration-tool

A modular TypeScript migration enforcement toolkit. Validate file extensions, run TypeScript type checking, and enforce migration standards with customizable checks and file providers.

## Features

- **Modular Architecture**: Combine file providers and checks to create custom workflows
- **Git Integration**: Check staged files, changed files, or specific paths
- **TypeScript Checking**: Run TypeScript compiler and report errors
- **Extension Enforcement**: Block JavaScript files during migration
- **Ignore Comments**: Temporarily suppress errors with `@ts-migration-ignore`
- **Interactive CLI**: Menu-driven interface for easy use
- **Configurable**: Custom config files and check options

## Installation

```bash
npm install @siteone/ts-migration-tool typescript
# or
yarn add @siteone/ts-migration-tool typescript
# or
pnpm add @siteone/ts-migration-tool typescript
```

## Quick Start

### CLI Usage

```bash
# Interactive menu
npx ts-migration

# Check staged files (for pre-commit hooks)
npx ts-migration staged

# Check changed files
npx ts-migration changed

# Check specific path
npx ts-migration path ./src

# View current configuration
npx ts-migration config

# Show help
npx ts-migration help
```

### Pre-commit Hook (with Husky)

```bash
# .husky/pre-commit
npx ts-migration staged
```

### Programmatic Usage

```typescript
import {
  TypeScriptMigrationTool,
  Config,
  ChangedFilesProvider,
} from '@siteone/ts-migration-tool'

// Load config with defaults (StagedFilesProvider)
const config = await Config.load()
const tool = new TypeScriptMigrationTool(config.value)
await tool.run() // Exits with code 1 on errors

// Load config with custom provider
const config = await Config.load({ provider: new ChangedFilesProvider() })

// Create config programmatically (no file loading)
const config = Config.from({
  checks: [
    { Check: ExtensionCheck },
    { Check: TypeScriptCheck, options: { tsconfigPath: 'tsconfig.build.json' } }
  ],
  exitOnError: false
})
const result = await new TypeScriptMigrationTool(config.value).run()
```

## Configuration File

Create `ts-migration.config.mjs` (or `.js`, `.cjs`):

```javascript
import {
  ExtensionCheck,
  TypeScriptCheck,
  UnusedIgnoreCheck,
  CodebaseUnusedIgnoreCheck,
} from '@siteone/ts-migration-tool'

export default {
  checks: [
    { Check: ExtensionCheck, options: { severity: 'error' } },
    { Check: TypeScriptCheck, options: { severity: 'error' } },
    { Check: UnusedIgnoreCheck, options: { severity: 'warning' } },
    { Check: CodebaseUnusedIgnoreCheck, options: { severity: 'error' } },
  ],
  // Glob patterns for files/folders to ignore from all checks
  ignorePatterns: [
    'node_modules/**',
    'dist/**',
    '*.config.js',
  ],
}
```

## Ignore Comments

Temporarily suppress errors during migration:

```typescript
// @ts-migration-ignore(TypeScript): Legacy code, will fix in AB-1234
const oldCode = legacyFunction() // TypeScript error suppressed

// @ts-migration-ignore(Extension): Server-side only, no types needed
// (in a .js file)
```

**File-level ignores** (downgrade all errors in a file to warnings):

```typescript
// @ts-migration-ignore-file(TypeScript): Config file must be JS
```

**Skip file** (skip all checks for a file entirely):

```typescript
// @ts-migration-skip-file: This file is not part of the migration
```

**Supported formats:**

- Line comment: `// @ts-migration-ignore(CheckType): reason`
- Block comment: `/@ts-migration-ignore(CheckType): reason/`
- JSX comment: `{/@ts-migration-ignore(CheckType): reason/}` (JSX)
- File-level ignore: `// @ts-migration-ignore-file(CheckType): reason`
- Skip file: `// @ts-migration-skip-file: reason`

**Behavior:**

- `@ts-migration-ignore` / `@ts-migration-ignore-file`: Downgrade severity from error to warning
- `@ts-migration-skip-file`: Skip all checks for the file entirely
- All comments require a reason explaining why

## Two-Stage Execution Model

The tool runs checks in two stages:

1. **Stage 1 (run)**: All checks execute in parallel, producing raw diagnostics
2. **Stage 2 (postProcess)**: Checks run sequentially with access to all results

This enables:

- UnusedIgnoreCheck to see which errors were found by other checks
- Custom checks to cross-reference results from other checks

## Creating Custom Checks

Extend the Check abstract class to create custom validation rules.
See the source code of ExtensionCheck or TypeScriptCheck for examples.

## Roadmap

- Unit test suite
- Integration tests for CLI
- CI/CD pipeline

## License

MIT

## Classes

### GitService

Service for git operations.

Provides methods to retrieve files from a git repository based on their status
(staged, modified, tracked). Used internally by git-based file providers.

#### Example

```typescript
const git = new GitService()

// Get files staged for commit
const staged = await git.getStagedFiles()

// Get all modified/untracked files
const changed = await git.getChangedFiles()
```

#### Constructors

##### Constructor

```ts
new GitService(basePath?: string): GitService;
```

Creates a new GitService instance.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `basePath?` | `string` | Optional path to the git repository root. Defaults to current working directory. |

###### Returns

[`GitService`](#gitservice)

#### Methods

##### getStagedFiles()

```ts
getStagedFiles(): Promise<string[]>;
```

Get files that are staged for commit (in the git index).

###### Returns

`Promise`\<`string`[]\>

Promise resolving to array of staged file paths (relative to repo root)

###### Example

```typescript
const staged = await gitService.getStagedFiles()
// ['src/index.ts', 'src/utils.ts']
```

##### getChangedFiles()

```ts
getChangedFiles(): Promise<string[]>;
```

Get files that have been modified, created, or are untracked.

Includes:
- Modified tracked files
- Newly created files (not yet tracked)
- Untracked files

###### Returns

`Promise`\<`string`[]\>

Promise resolving to array of changed file paths (relative to repo root)

###### Example

```typescript
const changed = await gitService.getChangedFiles()
// ['src/modified.ts', 'src/new-file.ts']
```

##### getAllTrackedFiles()

```ts
getAllTrackedFiles(): Promise<string[]>;
```

Get all files tracked by git in the repository.

###### Returns

`Promise`\<`string`[]\>

Promise resolving to array of all tracked file paths (relative to repo root)

###### Example

```typescript
const allFiles = await gitService.getAllTrackedFiles()
// ['src/index.ts', 'src/utils.ts', 'package.json', ...]
```

***

### IgnoreCommentsParser

Parser for

#### Ts-migration-ignore

comments.

Loads files and extracts all ignore comments. Provides methods for
checks to find relevant ignore comments for their diagnostics.

Supported comment formats for line-level ignores:
- `// @ts-migration-ignore(CheckType): reason`
- `/* @ts-migration-ignore(CheckType): reason */`
- `{/* @ts-migration-ignore(CheckType): reason */}` (JSX)

Supported comment formats for file-level ignores (ignore entire file):
- `// @ts-migration-ignore-file(CheckType): reason`
- `/* @ts-migration-ignore-file(CheckType): reason */`
- `{/* @ts-migration-ignore-file(CheckType): reason */}` (JSX)

#### Example

```typescript
const parser = new IgnoreCommentsParser()
parser.loadFiles(['src/index.ts', 'src/utils.ts'])

// Find ignore comment for a specific diagnostic
const ignore = parser.findIgnoreForLine('src/index.ts', 42, 'TypeScript')

// Check if file is entirely ignored
const fileIgnore = parser.isFileIgnored('src/legacy.js', 'TypeScript')
```

#### Constructors

##### Constructor

```ts
new IgnoreCommentsParser(): IgnoreCommentsParser;
```

###### Returns

[`IgnoreCommentsParser`](#ignorecommentsparser)

#### Methods

##### loadFiles()

```ts
loadFiles(files: string[]): void;
```

Load files and extract all

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `files` | `string`[] | Array of file paths to load |

###### Returns

`void`

###### Ts-migration-ignore

comments.

##### getAllIgnoreComments()

```ts
getAllIgnoreComments(): IgnoreComment[];
```

Get all ignore comments from loaded files.

###### Returns

[`IgnoreComment`](#ignorecomment)[]

Array of all ignore comments

##### getAllFileIgnoreComments()

```ts
getAllFileIgnoreComments(): FileIgnoreComment[];
```

Get all file-level ignore comments from loaded files.

###### Returns

[`FileIgnoreComment`](#fileignorecomment)[]

Array of all file-level ignore comments

##### getAllSkipFileComments()

```ts
getAllSkipFileComments(): SkipFileComment[];
```

Get all skip-file comments from loaded files.

###### Returns

[`SkipFileComment`](#skipfilecomment)[]

Array of all skip-file comments

##### isFileSkipped()

```ts
isFileSkipped(file: string): SkipFileComment | null;
```

Check if a file should be skipped entirely from all checks.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `file` | `string` | File path to check |

###### Returns

[`SkipFileComment`](#skipfilecomment) \| `null`

The skip-file comment if found, or null

##### isFileIgnored()

```ts
isFileIgnored(file: string, checkType: string): FileIgnoreComment | null;
```

Check if a file has a file-level ignore comment for a given check type.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `file` | `string` | File path to check |
| `checkType` | `string` | Check type to match (e.g., "TypeScript") |

###### Returns

[`FileIgnoreComment`](#fileignorecomment) \| `null`

The file-level ignore comment if found, or null

##### findIgnoreForFile()

```ts
findIgnoreForFile(file: string, checkType: string): IgnoreComment | null;
```

Find any ignore comment in a file for a given check type.

Used for file-level checks like ExtensionCheck where the ignore comment
can appear anywhere in the file.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `file` | `string` | File path to search in |
| `checkType` | `string` | Check type to match (e.g., "Extension") |

###### Returns

[`IgnoreComment`](#ignorecomment) \| `null`

The first matching ignore comment, or null if not found

##### findIgnoreForLine()

```ts
findIgnoreForLine(
   file: string, 
   errorLine: number, 
   checkType: string): IgnoreComment | null;
```

Find an ignore comment above a specific line for a given check type.

Searches consecutive comment lines above the error line for a matching

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `file` | `string` | File path to search in |
| `errorLine` | `number` | Line number of the diagnostic (1-based) |
| `checkType` | `string` | Check type to match (e.g., "TypeScript") |

###### Returns

[`IgnoreComment`](#ignorecomment) \| `null`

The matching ignore comment, or null if not found

###### Ts-migration-ignore

comment with the specified check type.

***

### TypeScriptMigrationTool

Main orchestrator for TypeScript migration checks.

Combines a file provider (source of files) with one or more checks
(validations) to create a complete migration checking workflow.

The constructor validates the configuration and throws `ConfigValidationError`
if invalid. Use `Config.load()` or `Config.from()` to load and merge configuration.

#### Examples

```typescript
// Load config with defaults (StagedFilesProvider)
const config = await Config.load()
const tool = new TypeScriptMigrationTool(config.value)
await tool.run() // Exits with code 1 on errors
```

```typescript
// Load config with custom provider
const config = await Config.load({ provider: new ChangedFilesProvider() })
await new TypeScriptMigrationTool(config.value).run()
```

```typescript
// Disable automatic exit to handle result manually
const config = Config.from({ exitOnError: false })
const result = await new TypeScriptMigrationTool(config.value).run()
```

#### Constructors

##### Constructor

```ts
new TypeScriptMigrationTool(config: {
  provider: FileProvider;
  checks: {
     Check: CheckConstructor;
     options?: Record<string, unknown>;
  }[];
  exitOnError: boolean;
  sourceExtensions: readonly string[];
  ignorePatterns?: string[];
}): TypeScriptMigrationTool;
```

Creates a new TypeScriptMigrationTool instance.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `config` | \{ `provider`: [`FileProvider`](#fileprovider); `checks`: \{ `Check`: [`CheckConstructor`](#checkconstructor); `options?`: `Record`\<`string`, `unknown`\>; \}[]; `exitOnError`: `boolean`; `sourceExtensions`: readonly `string`[]; `ignorePatterns?`: `string`[]; \} | Configuration object. Will be validated on construction. |
| `config.provider` | [`FileProvider`](#fileprovider) | - |
| `config.checks` | \{ `Check`: [`CheckConstructor`](#checkconstructor); `options?`: `Record`\<`string`, `unknown`\>; \}[] | - |
| `config.exitOnError` | `boolean` | - |
| `config.sourceExtensions` | readonly `string`[] | - |
| `config.ignorePatterns?` | `string`[] | Glob patterns for files/folders to ignore from all checks |

###### Returns

[`TypeScriptMigrationTool`](#typescriptmigrationtool)

###### Throws

ConfigValidationError if the configuration is invalid

#### Methods

##### run()

```ts
run(): Promise<MigrationToolResult>;
```

Run all checks, log results, and exit on errors if configured.

This is the main entry point that:
1. Runs all configured checks
2. Logs the results using the logger
3. Exits with code 1 if hasErrors and exitOnError is true

###### Returns

`Promise`\<[`MigrationToolResult`](#migrationtoolresult)\>

Promise resolving to aggregated result from all checks

##### runChecks()

```ts
runChecks(): Promise<MigrationToolResult>;
```

Run all configured checks without logging or exit behavior.

Executes checks in two stages:
1. Stage 1: Run all checks to get raw diagnostics
2. Stage 2: Post-process all checks (with access to all results)

Use this method when you want to handle logging and exit yourself.

###### Returns

`Promise`\<[`MigrationToolResult`](#migrationtoolresult)\>

Promise resolving to aggregated result from all checks

***

### `abstract` Check

Abstract base class for checks.

Checks are responsible for validating files and reporting any issues found.
Each check focuses on a specific validation concern (e.g., file extensions,
TypeScript errors, linting rules).

Checks run in two stages:
1. `run()` - Produce raw diagnostics
2. `postProcess()` - Process ignore comments (with access to all check results)

#### Example

```typescript
// Creating a custom check
class MyCustomCheck extends Check {
  readonly name = 'My Custom Check'
  readonly checkType = 'MyCustom'
  private severity: Severity

  constructor(options: { severity?: Severity } = {}) {
    super()
    this.severity = options.severity ?? 'error'
  }

  async run(files: string[], context: CheckContext): Promise<CheckResult> {
    const issues = this.validate(files)
    return {
      checkName: this.name,
      checkType: this.checkType,
      diagnostics: issues.map(issue => ({
        file: issue.file,
        message: issue.message,
        severity: this.severity
      }))
    }
  }
}
```

#### See

 - [ExtensionCheck](#extensioncheck) - Check for disallowed file extensions
 - [TypeScriptCheck](#typescriptcheck) - Check for TypeScript compiler errors

#### Extended by

- [`ExtensionCheck`](#extensioncheck)
- [`TypeScriptCheck`](#typescriptcheck)
- [`UnusedIgnoreCheck`](#unusedignorecheck)
- [`CodebaseUnusedIgnoreCheck`](#codebaseunusedignorecheck)

#### Constructors

##### Constructor

```ts
new Check(): Check;
```

###### Returns

[`Check`](#check)

#### Methods

##### run()

```ts
abstract run(files: string[], context: CheckContext): Promise<CheckResult>;
```

Stage 1: Run the check on the provided files.

Should return raw diagnostics without processing ignore comments.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `files` | `string`[] | Array of file paths to validate |
| `context` | [`CheckContext`](#checkcontext) | Check context with ignore store (allResults is empty in stage 1) |

###### Returns

`Promise`\<[`CheckResult`](#checkresult)\>

Promise resolving to check result with raw diagnostics

##### postProcess()

```ts
postProcess(result: CheckResult, _context: CheckContext): CheckResult;
```

Stage 2: Post-process diagnostics with access to all check results.

Override this method to process

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `result` | [`CheckResult`](#checkresult) | The result from this check's run() method |
| `_context` | [`CheckContext`](#checkcontext) | - |

###### Returns

[`CheckResult`](#checkresult)

Processed check result

###### Ts-migration-ignore

comments.
Default implementation returns the result unchanged.

#### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="optionsschema-1"></a> `optionsSchema` | `static` | `ZodType` | Zod schema for validating constructor options. Override in subclasses to define check-specific options. Default accepts empty object (no options). |
| <a id="name"></a> `name` | `abstract` | `string` | Human-readable name of the check. Used for logging and result reporting. |
| <a id="checktype-3"></a> `checkType` | `abstract` | `string` | Check type identifier used for matching ignore comments. Should match the value used in @ts-migration-ignore(CheckType) comments. E.g., "TypeScript", "Extension", "UnusedIgnore" |

***

### CodebaseUnusedIgnoreCheck

Check that scans the entire codebase for unused

#### Ts-migration-ignore

comments.

Unlike UnusedIgnoreCheck which only checks staged/changed files, this check
scans all files in the codebase that contain ignore comments. This is useful
for periodic cleanup to find stale ignore comments that are no longer needed.

This check:
1. Finds all files with

#### Ts-migration-ignore

comments
2. Runs all configured checks on those files
3. Reports any ignore comments that don't suppress any errors

#### Example

```typescript
// Add to your config (opt-in)
const config = {
  checks: [
    { Check: ExtensionCheck },
    { Check: TypeScriptCheck },
    { Check: UnusedIgnoreCheck },
    { Check: CodebaseUnusedIgnoreCheck }, // Scans full codebase
  ]
}
```

#### Extends

- [`Check`](#check)

#### Constructors

##### Constructor

```ts
new CodebaseUnusedIgnoreCheck(options: {
  severity?: "error" | "warning" | "info";
}): CodebaseUnusedIgnoreCheck;
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | \{ `severity?`: `"error"` \| `"warning"` \| `"info"`; \} | - |
| `options.severity?` | `"error"` \| `"warning"` \| `"info"` | Severity level for unused ignore warnings. Defaults to 'warning' |

###### Returns

[`CodebaseUnusedIgnoreCheck`](#codebaseunusedignorecheck)

###### Overrides

[`Check`](#check).[`constructor`](#constructor-3)

#### Methods

##### postProcess()

```ts
postProcess(result: CheckResult, _context: CheckContext): CheckResult;
```

Stage 2: Post-process diagnostics with access to all check results.

Override this method to process

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `result` | [`CheckResult`](#checkresult) | The result from this check's run() method |
| `_context` | [`CheckContext`](#checkcontext) | - |

###### Returns

[`CheckResult`](#checkresult)

Processed check result

###### Ts-migration-ignore

comments.
Default implementation returns the result unchanged.

###### Inherited from

[`Check`](#check).[`postProcess`](#postprocess)

##### run()

```ts
run(_files: string[], context: CheckContext): Promise<CheckResult>;
```

Run the codebase-wide unused ignore check.

Creates a new TypeScriptMigrationTool instance with IgnoreCommentsFilesProvider
to scan all files with ignore comments. Ensures UnusedIgnoreCheck is included
in the checks, then returns the unused ignore results.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `_files` | `string`[] | Files from the original provider (not used) |
| `context` | [`CheckContext`](#checkcontext) | Check context with config |

###### Returns

`Promise`\<[`CheckResult`](#checkresult)\>

Promise resolving to check result with unused ignore diagnostics

###### Overrides

[`Check`](#check).[`run`](#run-2)

#### Properties

| Property | Modifier | Type | Default value | Description | Overrides |
| ------ | ------ | ------ | ------ | ------ | ------ |
| <a id="name-1"></a> `name` | `readonly` | `"Codebase Unused Ignore Check"` | `'Codebase Unused Ignore Check'` | Human-readable name of the check. Used for logging and result reporting. | [`Check`](#check).[`name`](#name) |
| <a id="checktype-4"></a> `checkType` | `readonly` | `"CodebaseUnusedIgnore"` | `'CodebaseUnusedIgnore'` | Check type identifier used for matching ignore comments. Should match the value used in @ts-migration-ignore(CheckType) comments. E.g., "TypeScript", "Extension", "UnusedIgnore" | [`Check`](#check).[`checkType`](#checktype-3) |
| <a id="optionsschema-2"></a> `optionsSchema` | `static` | `ZodObject`\<\{ `severity`: `ZodOptional`\<`ZodEnum`\<\[`"error"`, `"warning"`, `"info"`\]\>\>; \}, `"strict"`, `ZodTypeAny`, \{ `severity?`: `"error"` \| `"warning"` \| `"info"`; \}, \{ `severity?`: `"error"` \| `"warning"` \| `"info"`; \}\> | `CodebaseUnusedIgnoreCheckOptionsSchema` | Zod schema for validating constructor options | [`Check`](#check).[`optionsSchema`](#optionsschema-1) |

***

### ExtensionCheck

Check that validates file extensions.

Reports a diagnostic for each JavaScript file (.js, .jsx) found.
Used to enforce TypeScript-only commits during migration.

#### Examples

```typescript
const check = new ExtensionCheck()
const result = check.run(['src/index.ts', 'src/legacy.js'])
// result.diagnostics contains error for legacy.js
```

```typescript
// With custom severity
const check = new ExtensionCheck({ severity: 'warning' })
const result = check.run(['src/legacy.js'])
// result.diagnostics[0].severity === 'warning'
```

#### Extends

- [`Check`](#check)

#### Constructors

##### Constructor

```ts
new ExtensionCheck(options: {
  severity?: "error" | "warning" | "info";
}): ExtensionCheck;
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | \{ `severity?`: `"error"` \| `"warning"` \| `"info"`; \} | - |
| `options.severity?` | `"error"` \| `"warning"` \| `"info"` | Severity level for extension violations. Defaults to 'error' |

###### Returns

[`ExtensionCheck`](#extensioncheck)

###### Overrides

[`Check`](#check).[`constructor`](#constructor-3)

#### Methods

##### run()

```ts
run(files: string[], _context: CheckContext): Promise<CheckResult>;
```

Stage 1: Run the extension check on provided files.

Returns raw diagnostics without processing ignore comments.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `files` | `string`[] | Array of file paths to check |
| `_context` | [`CheckContext`](#checkcontext) | Check context (not used in stage 1) |

###### Returns

`Promise`\<[`CheckResult`](#checkresult)\>

Promise resolving to CheckResult with diagnostics for any JavaScript files found

###### Overrides

[`Check`](#check).[`run`](#run-2)

##### postProcess()

```ts
postProcess(result: CheckResult, context: CheckContext): CheckResult;
```

Stage 2: Process

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `result` | [`CheckResult`](#checkresult) | The result from run() |
| `context` | [`CheckContext`](#checkcontext) | Check context with ignore parser |

###### Returns

[`CheckResult`](#checkresult)

Processed check result with ignore comments applied

###### Ts-migration-ignore

and

###### Ts-migration-ignore-file

comments.

For ExtensionCheck, an ignore comment anywhere in the file applies to
the entire file (since the diagnostic is about the file extension).
Both @ts-migration-ignore(Extension) and @ts-migration-ignore-file(Extension)
are supported.

###### Overrides

[`Check`](#check).[`postProcess`](#postprocess)

#### Properties

| Property | Modifier | Type | Default value | Description | Overrides |
| ------ | ------ | ------ | ------ | ------ | ------ |
| <a id="name-2"></a> `name` | `readonly` | `"Extension Check"` | `'Extension Check'` | Human-readable name of the check. Used for logging and result reporting. | [`Check`](#check).[`name`](#name) |
| <a id="checktype-5"></a> `checkType` | `readonly` | `"Extension"` | `'Extension'` | Check type identifier used for matching ignore comments. Should match the value used in @ts-migration-ignore(CheckType) comments. E.g., "TypeScript", "Extension", "UnusedIgnore" | [`Check`](#check).[`checkType`](#checktype-3) |
| <a id="optionsschema-3"></a> `optionsSchema` | `static` | `ZodObject`\<\{ `severity`: `ZodOptional`\<`ZodEnum`\<\[`"error"`, `"warning"`, `"info"`\]\>\>; \}, `"strict"`, `ZodTypeAny`, \{ `severity?`: `"error"` \| `"warning"` \| `"info"`; \}, \{ `severity?`: `"error"` \| `"warning"` \| `"info"`; \}\> | `ExtensionCheckOptionsSchema` | Zod schema for validating constructor options | [`Check`](#check).[`optionsSchema`](#optionsschema-1) |

***

### TypeScriptCheck

Check that runs the TypeScript compiler and reports type errors.

Only checks files with .ts or .tsx extensions. Errors from other files
(e.g., imported dependencies) are filtered out to show only errors
from the files being checked.

#### Examples

```typescript
// Using default tsconfig.json
const check = new TypeScriptCheck()
const result = check.run(['src/index.ts', 'src/utils.ts'])
```

```typescript
// Using custom tsconfig path and severity
const check = new TypeScriptCheck({ tsconfigPath: 'tsconfig.build.json', severity: 'warning' })
const result = check.run(['src/index.ts'])
```

#### Extends

- [`Check`](#check)

#### Constructors

##### Constructor

```ts
new TypeScriptCheck(options: {
  tsconfigPath?: string;
  severity?: "error" | "warning" | "info";
}): TypeScriptCheck;
```

Creates a new TypeScriptCheck instance.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | \{ `tsconfigPath?`: `string`; `severity?`: `"error"` \| `"warning"` \| `"info"`; \} | Configuration options for the check |
| `options.tsconfigPath?` | `string` | Path to tsconfig.json file. Defaults to 'tsconfig.json' |
| `options.severity?` | `"error"` \| `"warning"` \| `"info"` | Severity level for TypeScript errors. Defaults to 'error' |

###### Returns

[`TypeScriptCheck`](#typescriptcheck)

###### Throws

Error if the tsconfig file cannot be read or parsed

###### Overrides

[`Check`](#check).[`constructor`](#constructor-3)

#### Methods

##### run()

```ts
run(files: string[], _context: CheckContext): Promise<CheckResult>;
```

Stage 1: Run TypeScript type checking on the provided files.

Returns raw diagnostics without processing ignore comments.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `files` | `string`[] | Array of file paths to check |
| `_context` | [`CheckContext`](#checkcontext) | Check context (not used in stage 1) |

###### Returns

`Promise`\<[`CheckResult`](#checkresult)\>

Promise resolving to CheckResult with raw diagnostics for any TypeScript errors found

###### Overrides

[`Check`](#check).[`run`](#run-2)

##### postProcess()

```ts
postProcess(result: CheckResult, context: CheckContext): CheckResult;
```

Stage 2: Process

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `result` | [`CheckResult`](#checkresult) | The result from run() |
| `context` | [`CheckContext`](#checkcontext) | Check context with ignore store |

###### Returns

[`CheckResult`](#checkresult)

Processed check result with ignore comments applied

###### Ts-migration-ignore

and

###### Ts-migration-ignore-file

comments.

Finds ignore comments above diagnostics and downgrades their severity.
Also handles file-level ignores that suppress all diagnostics in a file.

###### Overrides

[`Check`](#check).[`postProcess`](#postprocess)

#### Properties

| Property | Modifier | Type | Default value | Description | Overrides |
| ------ | ------ | ------ | ------ | ------ | ------ |
| <a id="name-3"></a> `name` | `readonly` | `"TypeScript Check"` | `'TypeScript Check'` | Human-readable name of the check. Used for logging and result reporting. | [`Check`](#check).[`name`](#name) |
| <a id="checktype-6"></a> `checkType` | `readonly` | `"TypeScript"` | `'TypeScript'` | Check type identifier used for matching ignore comments. Should match the value used in @ts-migration-ignore(CheckType) comments. E.g., "TypeScript", "Extension", "UnusedIgnore" | [`Check`](#check).[`checkType`](#checktype-3) |
| <a id="optionsschema-4"></a> `optionsSchema` | `static` | `ZodObject`\<\{ `tsconfigPath`: `ZodOptional`\<`ZodString`\>; `severity`: `ZodOptional`\<`ZodEnum`\<\[`"error"`, `"warning"`, `"info"`\]\>\>; \}, `"strict"`, `ZodTypeAny`, \{ `tsconfigPath?`: `string`; `severity?`: `"error"` \| `"warning"` \| `"info"`; \}, \{ `tsconfigPath?`: `string`; `severity?`: `"error"` \| `"warning"` \| `"info"`; \}\> | `TypeScriptCheckOptionsSchema` | Zod schema for validating constructor options | [`Check`](#check).[`optionsSchema`](#optionsschema-1) |

***

### UnusedIgnoreCheck

Check that detects unused

#### Ts-migration-ignore

comments.

When a developer adds `@ts-migration-ignore(CheckType): reason` to suppress
an error, and later the error is fixed, the ignore comment becomes stale.
This check finds those unused ignore comments and reports them.

For each ignore comment, this check looks through all diagnostics to see if
any diagnostic would be suppressed by it. If no matching diagnostic is found,
the ignore comment is reported as unused.

#### Example

```typescript
const check = new UnusedIgnoreCheck()
// In stage 2, with access to all raw diagnostics:
const result = check.postProcess(emptyResult, context)
// result.diagnostics contains warnings for unused ignore comments
```

#### Extends

- [`Check`](#check)

#### Constructors

##### Constructor

```ts
new UnusedIgnoreCheck(options: {
  severity?: "error" | "warning" | "info";
}): UnusedIgnoreCheck;
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | \{ `severity?`: `"error"` \| `"warning"` \| `"info"`; \} | - |
| `options.severity?` | `"error"` \| `"warning"` \| `"info"` | Severity level for unused ignore warnings. Defaults to 'warning' |

###### Returns

[`UnusedIgnoreCheck`](#unusedignorecheck)

###### Overrides

[`Check`](#check).[`constructor`](#constructor-3)

#### Methods

##### run()

```ts
run(_files: string[], _context: CheckContext): Promise<CheckResult>;
```

Stage 1: No raw diagnostics.

This check doesn't produce any diagnostics in stage 1.
All detection happens in postProcess.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `_files` | `string`[] | Array of file paths (not used) |
| `_context` | [`CheckContext`](#checkcontext) | Check context (not used) |

###### Returns

`Promise`\<[`CheckResult`](#checkresult)\>

Promise resolving to empty check result

###### Overrides

[`Check`](#check).[`run`](#run-2)

##### postProcess()

```ts
postProcess(_result: CheckResult, context: CheckContext): CheckResult;
```

Stage 2: Find unused ignore comments.

For each ignore comment, checks if there's a matching diagnostic in allResults
that would be suppressed by it. Reports ignore comments that don't match any diagnostic.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `_result` | [`CheckResult`](#checkresult) | The result from run() (empty, not used) |
| `context` | [`CheckContext`](#checkcontext) | Check context with ignore store and all check results |

###### Returns

[`CheckResult`](#checkresult)

Check result with diagnostics for unused ignore comments

###### Overrides

[`Check`](#check).[`postProcess`](#postprocess)

#### Properties

| Property | Modifier | Type | Default value | Description | Overrides |
| ------ | ------ | ------ | ------ | ------ | ------ |
| <a id="name-4"></a> `name` | `readonly` | `"Unused Ignore Check"` | `'Unused Ignore Check'` | Human-readable name of the check. Used for logging and result reporting. | [`Check`](#check).[`name`](#name) |
| <a id="checktype-7"></a> `checkType` | `readonly` | `"UnusedIgnore"` | `'UnusedIgnore'` | Check type identifier used for matching ignore comments. Should match the value used in @ts-migration-ignore(CheckType) comments. E.g., "TypeScript", "Extension", "UnusedIgnore" | [`Check`](#check).[`checkType`](#checktype-3) |
| <a id="optionsschema-5"></a> `optionsSchema` | `static` | `ZodObject`\<\{ `severity`: `ZodOptional`\<`ZodEnum`\<\[`"error"`, `"warning"`, `"info"`\]\>\>; \}, `"strict"`, `ZodTypeAny`, \{ `severity?`: `"error"` \| `"warning"` \| `"info"`; \}, \{ `severity?`: `"error"` \| `"warning"` \| `"info"`; \}\> | `UnusedIgnoreCheckOptionsSchema` | Zod schema for validating constructor options | [`Check`](#check).[`optionsSchema`](#optionsschema-1) |

***

### ConfigValidationError

Custom error class for configuration validation failures.
Provides structured access to validation issues.

#### Example

```typescript
try {
  Config.validate(invalidConfig)
} catch (error) {
  if (error instanceof ConfigValidationError) {
    console.log(error.issues) // [{ path: 'exitOnError', message: 'Expected boolean' }]
  }
}
```

#### Extends

- `Error`

#### Constructors

##### Constructor

```ts
new ConfigValidationError(message: string, issues: ValidationIssue[]): ConfigValidationError;
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `string` |
| `issues` | [`ValidationIssue`](#validationissue)[] |

###### Returns

[`ConfigValidationError`](#configvalidationerror)

###### Overrides

```ts
Error.constructor
```

#### Methods

##### fromIssues()

```ts
static fromIssues(issues: ValidationIssue[]): ConfigValidationError;
```

Create a ConfigValidationError from an array of issues.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `issues` | [`ValidationIssue`](#validationissue)[] |

###### Returns

[`ConfigValidationError`](#configvalidationerror)

##### captureStackTrace()

```ts
static captureStackTrace(targetObject: object, constructorOpt?: Function): void;
```

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

###### Returns

`void`

###### Inherited from

```ts
Error.captureStackTrace
```

##### prepareStackTrace()

```ts
static prepareStackTrace(err: Error, stackTraces: CallSite[]): any;
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `err` | `Error` |
| `stackTraces` | `CallSite`[] |

###### Returns

`any`

###### See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

###### Inherited from

```ts
Error.prepareStackTrace
```

#### Properties

| Property | Modifier | Type | Description | Inherited from |
| ------ | ------ | ------ | ------ | ------ |
| <a id="issues"></a> `issues` | `readonly` | [`ValidationIssue`](#validationissue)[] | - | - |
| <a id="stacktracelimit"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `Error.stackTraceLimit` |
| <a id="cause"></a> `cause?` | `public` | `unknown` | - | `Error.cause` |
| <a id="name-5"></a> `name` | `public` | `string` | - | `Error.name` |
| <a id="message-2"></a> `message` | `public` | `string` | - | `Error.message` |
| <a id="stack"></a> `stack?` | `public` | `string` | - | `Error.stack` |

***

### Config

Configuration manager for TypeScriptMigrationTool.

Handles loading configuration from files and merging with defaults.
Default provider is StagedFilesProvider.
Validation happens in TypeScriptMigrationTool constructor.

#### Example

```typescript
// Load with defaults (StagedFilesProvider)
const config = await Config.load()
const tool = new TypeScriptMigrationTool(config.value)

// Load with custom provider
const config = await Config.load({ provider: new ChangedFilesProvider() })

// Load from custom config file
const config = await Config.load({}, 'custom-config.ts')
```

#### Methods

##### print()

```ts
print(): void;
```

Print the configuration to the console.

###### Returns

`void`

##### load()

```ts
static load(runtimeConfig: Record<string, unknown>, customPath?: string): Promise<Config>;
```

Load and merge configuration from file and runtime overrides.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `runtimeConfig` | `Record`\<`string`, `unknown`\> | Runtime configuration overrides (optional, defaults to StagedFilesProvider) |
| `customPath?` | `string` | Custom config file path (from --config argument) |

###### Returns

`Promise`\<[`Config`](#config-1)\>

Config instance (validation happens in TypeScriptMigrationTool)

###### Example

```typescript
// Use all defaults
const config = await Config.load()

// Override provider
const config = await Config.load({ provider: new ChangedFilesProvider() })
```

##### from()

```ts
static from(config: Record<string, unknown>): Config;
```

Create a Config from already-merged configuration (skips file loading).

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `config` | `Record`\<`string`, `unknown`\> | Configuration object (will be merged with defaults) |

###### Returns

[`Config`](#config-1)

Config instance

##### validate()

```ts
static validate(config: unknown): void;
```

Validate configuration.
Collects all validation errors (config + check options) before throwing.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `config` | `unknown` |

###### Returns

`void`

###### Throws

ConfigValidationError if validation fails

#### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="value"></a> `value` | `readonly` | \{ `provider`: [`FileProvider`](#fileprovider); `checks`: \{ `Check`: [`CheckConstructor`](#checkconstructor); `options?`: `Record`\<`string`, `unknown`\>; \}[]; `exitOnError`: `boolean`; `sourceExtensions`: readonly `string`[]; `ignorePatterns?`: `string`[]; \} | The merged configuration (validated by TypeScriptMigrationTool) |
| `value.provider` | `public` | [`FileProvider`](#fileprovider) | - |
| `value.checks` | `public` | \{ `Check`: [`CheckConstructor`](#checkconstructor); `options?`: `Record`\<`string`, `unknown`\>; \}[] | - |
| `value.exitOnError` | `public` | `boolean` | - |
| `value.sourceExtensions` | `public` | readonly `string`[] | - |
| `value.ignorePatterns?` | `public` | `string`[] | Glob patterns for files/folders to ignore from all checks |
| <a id="filepath"></a> `filePath` | `readonly` | `string` \| `undefined` | Path to the config file that was loaded, or undefined if using defaults |

***

### ChangedFilesProvider

File provider that returns modified and untracked files in git.

Use this provider to check all files that have been changed in the working
directory, regardless of whether they are staged or not.

#### Examples

```typescript
const provider = new ChangedFilesProvider()
const files = await provider.getFiles()
// ['src/modified.ts', 'src/untracked-file.tsx']
```

```typescript
// With custom GitService (e.g., for testing)
const gitService = new GitService('/path/to/repo')
const provider = new ChangedFilesProvider(gitService)
```

#### Extends

- [`FileProvider`](#fileprovider)

#### Constructors

##### Constructor

```ts
new ChangedFilesProvider(gitService?: GitService): ChangedFilesProvider;
```

Creates a new ChangedFilesProvider instance.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `gitService?` | [`GitService`](#gitservice) | Optional GitService instance. If not provided, a new instance will be created using the current directory. |

###### Returns

[`ChangedFilesProvider`](#changedfilesprovider)

###### Overrides

[`FileProvider`](#fileprovider).[`constructor`](#constructor-10)

#### Methods

##### getFiles()

```ts
getFiles(): Promise<string[]>;
```

Get all modified, created, and untracked files.

###### Returns

`Promise`\<`string`[]\>

Promise resolving to array of changed file paths

###### Overrides

[`FileProvider`](#fileprovider).[`getFiles`](#getfiles-2)

#### Properties

| Property | Modifier | Type | Default value | Description | Overrides |
| ------ | ------ | ------ | ------ | ------ | ------ |
| <a id="name-6"></a> `name` | `readonly` | `"Changed Files"` | `'Changed Files'` | Human-readable name of the provider. Used for logging and result reporting. | [`FileProvider`](#fileprovider).[`name`](#name-7) |

***

### `abstract` FileProvider

Abstract base class for file providers.

File providers are responsible for supplying a list of files to be checked.
Implementations can source files from various places like git (staged/changed files),
filesystem (specific paths), or other sources.

#### Example

```typescript
// Creating a custom provider
class MyCustomProvider extends FileProvider {
  readonly name = 'My Custom Provider'

  async getFiles(): Promise<string[]> {
    return ['file1.ts', 'file2.ts']
  }
}
```

#### See

 - [StagedFilesProvider](#stagedfilesprovider) - Provider for git staged files
 - [ChangedFilesProvider](#changedfilesprovider) - Provider for git changed files
 - [PathProvider](#pathprovider) - Provider for specific file/folder paths

#### Extended by

- [`StagedFilesProvider`](#stagedfilesprovider)
- [`ChangedFilesProvider`](#changedfilesprovider)
- [`PathProvider`](#pathprovider)
- [`IgnoreCommentsFilesProvider`](#ignorecommentsfilesprovider)

#### Constructors

##### Constructor

```ts
new FileProvider(): FileProvider;
```

###### Returns

[`FileProvider`](#fileprovider)

#### Methods

##### getFiles()

```ts
abstract getFiles(): Promise<string[]>;
```

Get list of files from this provider.

###### Returns

`Promise`\<`string`[]\>

Promise resolving to an array of file paths (relative or absolute)

#### Properties

| Property | Modifier | Type | Description |
| ------ | ------ | ------ | ------ |
| <a id="name-7"></a> `name` | `abstract` | `string` | Human-readable name of the provider. Used for logging and result reporting. |

***

### IgnoreCommentsFilesProvider

File provider that returns files containing

#### Ts-migration-ignore

comments.

Scans the entire codebase for source files and filters to only those
that contain the ignore marker. Used by CodebaseUnusedIgnoreCheck to
find all files with ignore comments regardless of git status.

#### Examples

```typescript
const provider = new IgnoreCommentsFilesProvider()
const files = await provider.getFiles()
// ['src/legacy.ts', 'src/components/Button.tsx'] - files with ignore comments
```

```typescript
// With custom extensions and exclude dirs
const provider = new IgnoreCommentsFilesProvider({
  sourceExtensions: ['.ts', '.tsx'],
  excludeDirs: ['node_modules', 'build', 'vendor']
})
```

#### Extends

- [`FileProvider`](#fileprovider)

#### Constructors

##### Constructor

```ts
new IgnoreCommentsFilesProvider(options: IgnoreCommentsFilesProviderOptions): IgnoreCommentsFilesProvider;
```

Creates a new IgnoreCommentsFilesProvider instance.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`IgnoreCommentsFilesProviderOptions`](#ignorecommentsfilesprovideroptions) | Configuration options |

###### Returns

[`IgnoreCommentsFilesProvider`](#ignorecommentsfilesprovider)

###### Overrides

[`FileProvider`](#fileprovider).[`constructor`](#constructor-10)

#### Methods

##### getFiles()

```ts
getFiles(): Promise<string[]>;
```

Get all source files containing

###### Returns

`Promise`\<`string`[]\>

Promise resolving to array of file paths with ignore comments

###### Ts-migration-ignore

comments.

Uses TypeScript's built-in glob support to find files, then reads
each file in parallel to check for the ignore marker.

###### Overrides

[`FileProvider`](#fileprovider).[`getFiles`](#getfiles-2)

#### Properties

| Property | Modifier | Type | Default value | Description | Overrides |
| ------ | ------ | ------ | ------ | ------ | ------ |
| <a id="name-8"></a> `name` | `readonly` | `"Files with Ignore Comments"` | `'Files with Ignore Comments'` | Human-readable name of the provider. Used for logging and result reporting. | [`FileProvider`](#fileprovider).[`name`](#name-7) |

***

### PathProvider

File provider that returns files from a specific filesystem path.

Can be used with either a single file or a directory. When given a directory,
it can optionally traverse subdirectories recursively.

#### Examples

```typescript
// Check a single file
const provider = new PathProvider('src/components/Button.tsx')
const files = await provider.getFiles()
// ['src/components/Button.tsx']
```

```typescript
// Check all files in a directory (recursive)
const provider = new PathProvider('src/components')
const files = await provider.getFiles()
// ['src/components/Button.tsx', 'src/components/Input/Input.tsx', ...]
```

```typescript
// Check only top-level files in a directory (non-recursive)
const provider = new PathProvider('src/components', false)
const files = await provider.getFiles()
// ['src/components/Button.tsx'] (no subdirectory files)
```

#### Extends

- [`FileProvider`](#fileprovider)

#### Constructors

##### Constructor

```ts
new PathProvider(targetPath: string, recursive: boolean): PathProvider;
```

Creates a new PathProvider instance.

###### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `targetPath` | `string` | `undefined` | Path to a file or directory to provide files from |
| `recursive` | `boolean` | `true` | If true and path is a directory, include files from subdirectories. Defaults to true. |

###### Returns

[`PathProvider`](#pathprovider)

###### Overrides

[`FileProvider`](#fileprovider).[`constructor`](#constructor-10)

#### Methods

##### getFiles()

```ts
getFiles(): Promise<string[]>;
```

Get files from the configured path.

- If path is a file, returns array with that single file
- If path is a directory, returns all files (optionally recursive)
- If path doesn't exist or is neither file nor directory, returns empty array

###### Returns

`Promise`\<`string`[]\>

Promise resolving to array of file paths

###### Throws

Error if the path cannot be accessed

###### Overrides

[`FileProvider`](#fileprovider).[`getFiles`](#getfiles-2)

#### Properties

| Property | Modifier | Type | Description | Overrides |
| ------ | ------ | ------ | ------ | ------ |
| <a id="name-9"></a> `name` | `readonly` | `string` | Human-readable name of the provider. Used for logging and result reporting. | [`FileProvider`](#fileprovider).[`name`](#name-7) |

***

### StagedFilesProvider

File provider that returns files staged for commit in git.

Use this provider to check only files that are about to be committed,
typically in a pre-commit hook scenario.

#### Examples

```typescript
const provider = new StagedFilesProvider()
const files = await provider.getFiles()
// ['src/modified.ts', 'src/new-feature.tsx']
```

```typescript
// With custom GitService (e.g., for testing)
const gitService = new GitService('/path/to/repo')
const provider = new StagedFilesProvider(gitService)
```

#### Extends

- [`FileProvider`](#fileprovider)

#### Constructors

##### Constructor

```ts
new StagedFilesProvider(gitService?: GitService): StagedFilesProvider;
```

Creates a new StagedFilesProvider instance.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `gitService?` | [`GitService`](#gitservice) | Optional GitService instance. If not provided, a new instance will be created using the current directory. |

###### Returns

[`StagedFilesProvider`](#stagedfilesprovider)

###### Overrides

[`FileProvider`](#fileprovider).[`constructor`](#constructor-10)

#### Methods

##### getFiles()

```ts
getFiles(): Promise<string[]>;
```

Get all files currently staged for commit.

###### Returns

`Promise`\<`string`[]\>

Promise resolving to array of staged file paths

###### Overrides

[`FileProvider`](#fileprovider).[`getFiles`](#getfiles-2)

#### Properties

| Property | Modifier | Type | Default value | Description | Overrides |
| ------ | ------ | ------ | ------ | ------ | ------ |
| <a id="name-10"></a> `name` | `readonly` | `"Staged Files"` | `'Staged Files'` | Human-readable name of the provider. Used for logging and result reporting. | [`FileProvider`](#fileprovider).[`name`](#name-7) |

## Type Aliases

### IgnoreComment

```ts
type IgnoreComment = {
  file: string;
  line: number;
  checkType: string;
  reason: string;
};
```

Represents a parsed

#### Ts-migration-ignore

comment.

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="file"></a> `file` | `string` | File path (normalized with forward slashes) |
| <a id="line"></a> `line` | `number` | Line number where the comment is (1-based) |
| <a id="checktype"></a> `checkType` | `string` | Check type from the comment (e.g., "TypeScript", "Extension") |
| <a id="reason"></a> `reason` | `string` | Reason provided in the comment |

***

### FileIgnoreComment

```ts
type FileIgnoreComment = {
  file: string;
  line: number;
  checkType: string;
  reason: string;
};
```

Represents a file-level ignore comment (@ts-migration-ignore-file).

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="file-1"></a> `file` | `string` | File path (normalized with forward slashes) |
| <a id="line-1"></a> `line` | `number` | Line number where the comment is (1-based) |
| <a id="checktype-1"></a> `checkType` | `string` | Check type from the comment (e.g., "TypeScript", "Extension") |
| <a id="reason-1"></a> `reason` | `string` | Reason provided in the comment |

***

### SkipFileComment

```ts
type SkipFileComment = {
  file: string;
  line: number;
  reason: string;
};
```

Represents a skip-file comment (@ts-migration-skip-file).
Skips all checks for the entire file.

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="file-2"></a> `file` | `string` | File path (normalized with forward slashes) |
| <a id="line-2"></a> `line` | `number` | Line number where the comment is (1-based) |
| <a id="reason-2"></a> `reason` | `string` | Reason provided in the comment |

***

### LogLevel

```ts
type LogLevel = "debug" | "info" | "warn" | "error";
```

Log levels in order of severity (lowest to highest)

***

### MigrationToolResult

```ts
type MigrationToolResult = {
  provider: string;
  filesChecked: string[];
  results: CheckResult[];
  hasErrors: boolean;
};
```

Aggregated result from TypeScriptMigrationTool after running all checks.

#### Example

```typescript
const result: MigrationToolResult = {
  provider: 'Staged Files',
  filesChecked: ['src/index.ts', 'src/utils.ts'],
  results: [extensionCheckResult, typeScriptCheckResult],
  hasErrors: false
}
```

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="provider"></a> `provider` | `string` | Name of the file provider that supplied the files |
| <a id="fileschecked"></a> `filesChecked` | `string`[] | List of files that were checked |
| <a id="results"></a> `results` | [`CheckResult`](#checkresult)[] | Results from each individual check |
| <a id="haserrors"></a> `hasErrors` | `boolean` | Has errors - true if any diagnostic has severity 'error' |

***

### Severity

```ts
type Severity = z.infer<typeof SeveritySchema>;
```

Severity level for diagnostics.
- `error` - Causes exit code 1 when exitOnError is true
- `warning` - Logged but doesn't affect exit code
- `info` - Informational only

***

### Diagnostic

```ts
type Diagnostic = {
  file: string;
  line?: number;
  character?: number;
  message: string;
  severity: Severity;
  ignoreReason?: string;
};
```

A single diagnostic entry from a check.
Each diagnostic has its own severity, allowing checks to report
mixed severity issues in a single run.

#### Examples

```typescript
const diagnostic: Diagnostic = {
  file: 'src/components/Button.tsx',
  line: 42,
  character: 10,
  message: "Property 'onClick' is missing in type...",
  severity: 'error'
}
```

```typescript
// File-level diagnostic (no line/character)
const diagnostic: Diagnostic = {
  file: 'src/legacy.js',
  message: 'JavaScript file found. Please use TypeScript instead.',
  severity: 'error'
}
```

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="file-3"></a> `file` | `string` | Absolute or relative path to the file |
| <a id="line-3"></a> `line?` | `number` | Line number (1-based), omit if not applicable |
| <a id="character"></a> `character?` | `number` | Character position in line (1-based), omit if not applicable |
| <a id="message"></a> `message` | `string` | Human-readable message |
| <a id="severity-1"></a> `severity` | [`Severity`](#severity) | Severity level |
| <a id="ignorereason"></a> `ignoreReason?` | `string` | Reason from **Ts-migration-ignore** comment if this diagnostic was ignored |

***

### CheckResult

```ts
type CheckResult = {
  checkName: string;
  checkType: string;
  diagnostics: Diagnostic[];
};
```

Result of a single check execution.

#### Example

```typescript
const result: CheckResult = {
  checkName: 'TypeScript Check',
  checkType: 'TypeScript',
  diagnostics: [
    { file: 'src/index.ts', line: 1, character: 1, message: '...', severity: 'error' }
  ]
}
```

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="checkname"></a> `checkName` | `string` | Name of the check that produced this result |
| <a id="checktype-2"></a> `checkType` | `string` | Check type identifier (e.g., "TypeScript", "Extension", "UnusedIgnore") |
| <a id="diagnostics"></a> `diagnostics` | [`Diagnostic`](#diagnostic)[] | List of diagnostics found during the check |

***

### CheckContext

```ts
type CheckContext = {
  ignoreParser: IgnoreCommentsParser;
  allResults: CheckResult[];
  config: MigrationToolConfig;
};
```

Context passed to checks during execution.

Contains the ignore comment store for looking up

#### Ts-migration-ignore

comments,
results from all checks (populated in stage 2 / postProcess), and the full config.

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="ignoreparser"></a> `ignoreParser` | [`IgnoreCommentsParser`](#ignorecommentsparser) | Parser containing all **Ts-migration-ignore** comments from loaded files |
| <a id="allresults"></a> `allResults` | [`CheckResult`](#checkresult)[] | Results from all checks (empty in stage 1, populated in stage 2) |
| <a id="config"></a> `config` | [`MigrationToolConfig`](#migrationtoolconfig) | Full migration tool configuration |

***

### CheckConstructor()

```ts
type CheckConstructor = Check;
```

Constructor type for Check classes.
Accepts an optional options object for configuration.
Includes static `optionsSchema` for runtime validation.

```ts
type new CheckConstructor(options?: Record<string, unknown>): Check;
```

Constructor type for Check classes.
Accepts an optional options object for configuration.
Includes static `optionsSchema` for runtime validation.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `options?` | `Record`\<`string`, `unknown`\> |

#### Returns

[`Check`](#check)

#### Properties

| Property | Type |
| ------ | ------ |
| <a id="optionsschema"></a> `optionsSchema` | `ZodSchema` |

***

### CodebaseUnusedIgnoreCheckOptions

```ts
type CodebaseUnusedIgnoreCheckOptions = z.infer<typeof CodebaseUnusedIgnoreCheckOptionsSchema>;
```

Options for CodebaseUnusedIgnoreCheck.

***

### ExtensionCheckOptions

```ts
type ExtensionCheckOptions = z.infer<typeof ExtensionCheckOptionsSchema>;
```

Options for ExtensionCheck.

***

### TypeScriptCheckOptions

```ts
type TypeScriptCheckOptions = z.infer<typeof TypeScriptCheckOptionsSchema>;
```

Options for TypeScriptCheck.

***

### UnusedIgnoreCheckOptions

```ts
type UnusedIgnoreCheckOptions = z.infer<typeof UnusedIgnoreCheckOptionsSchema>;
```

Options for UnusedIgnoreCheck.

***

### ValidationIssue

```ts
type ValidationIssue = {
  path: string;
  message: string;
};
```

Structured validation issue

#### Properties

| Property | Type |
| ------ | ------ |
| <a id="path"></a> `path` | `string` |
| <a id="message-1"></a> `message` | `string` |

***

### CheckEntry

```ts
type CheckEntry = z.infer<typeof CheckEntrySchema>;
```

A check configuration with class reference and options.

#### Example

```typescript
// Simple check with no options
const entry: CheckEntry = {
  Check: ExtensionCheck
}

// Check with options
const entry: CheckEntry = {
  Check: TypeScriptCheck,
  options: { tsconfigPath: 'tsconfig.build.json' }
}
```

***

### MigrationToolConfig

```ts
type MigrationToolConfig = z.infer<typeof MigrationToolConfigSchema>;
```

Main configuration for TypeScriptMigrationTool (internal, fully resolved).

#### Example

```typescript
const config: MigrationToolConfig = {
  provider: new StagedFilesProvider(),
  checks: [
    { Check: ExtensionCheck },
    { Check: TypeScriptCheck }
  ],
  exitOnError: true
}
```

***

### IgnoreCommentsFilesProviderOptions

```ts
type IgnoreCommentsFilesProviderOptions = {
  sourceExtensions?: readonly string[];
  excludeDirs?: readonly string[];
};
```

Options for IgnoreCommentsFilesProvider.

#### Properties

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="sourceextensions"></a> `sourceExtensions?` | readonly `string`[] | Source extensions to scan. Defaults to ['.ts', '.tsx', '.js', '.jsx'] |
| <a id="excludedirs"></a> `excludeDirs?` | readonly `string`[] | Directories to exclude from scanning. Defaults to ['node_modules', 'build', '.next', 'dist', 'coverage'] |

## Variables

### logger

```ts
const logger: Logger;
```

Singleton logger instance

***

### SeveritySchema

```ts
const SeveritySchema: ZodEnum<["error", "warning", "info"]>;
```

Zod schema for severity levels.
Used to validate check severity options.

#### Example

```typescript
SeveritySchema.parse('error')    // OK
SeveritySchema.parse('fatal')    // Throws ZodError
```

***

### CodebaseUnusedIgnoreCheckOptionsSchema

```ts
const CodebaseUnusedIgnoreCheckOptionsSchema: ZodObject<{
  severity: ZodOptional<ZodEnum<["error", "warning", "info"]>>;
}, "strict", ZodTypeAny, {
  severity?: "error" | "warning" | "info";
}, {
  severity?: "error" | "warning" | "info";
}>;
```

Zod schema for CodebaseUnusedIgnoreCheck options.

#### Example

```typescript
CodebaseUnusedIgnoreCheckOptionsSchema.parse({ severity: 'error' })  // OK
CodebaseUnusedIgnoreCheckOptionsSchema.parse({ severity: 'fatal' })  // Throws ZodError
```

***

### ExtensionCheckOptionsSchema

```ts
const ExtensionCheckOptionsSchema: ZodObject<{
  severity: ZodOptional<ZodEnum<["error", "warning", "info"]>>;
}, "strict", ZodTypeAny, {
  severity?: "error" | "warning" | "info";
}, {
  severity?: "error" | "warning" | "info";
}>;
```

Zod schema for ExtensionCheck options.

#### Example

```typescript
ExtensionCheckOptionsSchema.parse({ severity: 'warning' })  // OK
ExtensionCheckOptionsSchema.parse({ severity: 'fatal' })    // Throws ZodError
```

***

### TypeScriptCheckOptionsSchema

```ts
const TypeScriptCheckOptionsSchema: ZodObject<{
  tsconfigPath: ZodOptional<ZodString>;
  severity: ZodOptional<ZodEnum<["error", "warning", "info"]>>;
}, "strict", ZodTypeAny, {
  tsconfigPath?: string;
  severity?: "error" | "warning" | "info";
}, {
  tsconfigPath?: string;
  severity?: "error" | "warning" | "info";
}>;
```

Zod schema for TypeScriptCheck options.

#### Example

```typescript
TypeScriptCheckOptionsSchema.parse({ tsconfigPath: 'tsconfig.build.json' })  // OK
TypeScriptCheckOptionsSchema.parse({ severity: 'fatal' })                     // Throws ZodError
```

***

### UnusedIgnoreCheckOptionsSchema

```ts
const UnusedIgnoreCheckOptionsSchema: ZodObject<{
  severity: ZodOptional<ZodEnum<["error", "warning", "info"]>>;
}, "strict", ZodTypeAny, {
  severity?: "error" | "warning" | "info";
}, {
  severity?: "error" | "warning" | "info";
}>;
```

Zod schema for UnusedIgnoreCheck options.

#### Example

```typescript
UnusedIgnoreCheckOptionsSchema.parse({ severity: 'error' })  // OK
UnusedIgnoreCheckOptionsSchema.parse({ severity: 'fatal' })  // Throws ZodError
```

***

### CheckEntrySchema

```ts
const CheckEntrySchema: ZodObject<{
  Check: ZodType<CheckConstructor, ZodTypeDef, CheckConstructor>;
  options: ZodOptional<ZodRecord<ZodString, ZodUnknown>>;
}, "strip", ZodTypeAny, {
  Check: CheckConstructor;
  options?: Record<string, unknown>;
}, {
  Check: CheckConstructor;
  options?: Record<string, unknown>;
}>;
```

Zod schema for check entry configuration.
Validates that Check is a class constructor and options is an optional object.

#### Example

```typescript
CheckEntrySchema.parse({ Check: ExtensionCheck })  // OK
CheckEntrySchema.parse({ Check: 'invalid' })       // Throws ZodError
```

***

### MigrationToolConfigSchema

```ts
const MigrationToolConfigSchema: ZodObject<{
  provider: ZodType<FileProvider, ZodTypeDef, FileProvider>;
  checks: ZodArray<ZodObject<{
     Check: ZodType<CheckConstructor, ZodTypeDef, CheckConstructor>;
     options: ZodOptional<ZodRecord<ZodString, ZodUnknown>>;
   }, "strip", ZodTypeAny, {
     Check: CheckConstructor;
     options?: Record<string, unknown>;
   }, {
     Check: CheckConstructor;
     options?: Record<string, unknown>;
  }>, "many">;
  exitOnError: ZodBoolean;
  sourceExtensions: ZodReadonly<ZodArray<ZodString, "many">>;
  ignorePatterns: ZodOptional<ZodArray<ZodString, "many">>;
}, "strict", ZodTypeAny, {
  provider: FileProvider;
  checks: {
     Check: CheckConstructor;
     options?: Record<string, unknown>;
  }[];
  exitOnError: boolean;
  sourceExtensions: readonly string[];
  ignorePatterns?: string[];
}, {
  provider: FileProvider;
  checks: {
     Check: CheckConstructor;
     options?: Record<string, unknown>;
  }[];
  exitOnError: boolean;
  sourceExtensions: readonly string[];
  ignorePatterns?: string[];
}>;
```

Zod schema for the merged MigrationToolConfig.
Used to validate configuration after defaults are applied.

#### Example

```typescript
const config = await Config.load()
MigrationToolConfigSchema.parse(config.value)  // Validates the config
```

***

### DEFAULT\_CHECKS

```ts
const DEFAULT_CHECKS: CheckEntry[];
```

Default checks used when none are specified.
Includes ExtensionCheck, TypeScriptCheck, and UnusedIgnoreCheck.

***

### DEFAULT\_SOURCE\_EXTENSIONS

```ts
const DEFAULT_SOURCE_EXTENSIONS: readonly [".ts", ".tsx", ".js", ".jsx"];
```

Default file extensions to parse for

#### Ts-migration-ignore

comments.

***

### DEFAULT\_EXCLUDE\_DIRS

```ts
const DEFAULT_EXCLUDE_DIRS: readonly ["node_modules", "build", ".next", "dist", "coverage"];
```

Default directories to exclude from scanning