0
# Type Coverage
1

2
Type Coverage is a comprehensive CLI tool and library for measuring TypeScript type coverage in codebases. It calculates the percentage of identifiers that have explicit types versus 'any' types, enabling developers to track and improve type safety during progressive migration from JavaScript to TypeScript.
3

4
## Package Information
5

6
- **Package Name**: type-coverage
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install -g type-coverage typescript`
10

11
## Core Imports
12

13
CLI usage (global installation):
14
```bash
15
type-coverage
16
```
17

18
For programmatic usage:
19
```typescript
20
import { lint, lintSync, FileAnyInfoKind } from "type-coverage-core";
21
```
22

23
CommonJS:
24
```javascript
25
const { lint, lintSync, FileAnyInfoKind } = require("type-coverage-core");
26
```
27

28
## Basic Usage
29

30
CLI usage:
31
```bash
32
# Basic type coverage check
33
type-coverage
34

35
# Check with minimum threshold
36
type-coverage --at-least 90
37

38
# Show detailed results
39
type-coverage --detail --at-least 80
40

41
# Use with specific project
42
type-coverage -p ./tsconfig.json --detail
43
```
44

45
Programmatic usage:
46
```typescript
47
import { lint } from "type-coverage-core";
48

49
// Analyze project type coverage
50
const result = await lint("./", {
51
  strict: true,
52
  detail: true,
53
  enableCache: true
54
});
55

56
console.log(`Coverage: ${result.correctCount}/${result.totalCount} (${(result.correctCount/result.totalCount*100).toFixed(2)}%)`);
57
```
58

59
## Architecture
60

61
Type Coverage consists of two main components:
62

63
- **CLI Tool**: Command-line interface providing comprehensive options for type coverage analysis and reporting
64
- **Core Library**: Programmatic API (`type-coverage-core`) for integrating type coverage analysis into build pipelines and development tools
65
- **Type Analysis Engine**: Deep TypeScript AST analysis to identify 'any' types, unsafe assertions, and type coverage metrics
66
- **Caching System**: Performance optimization through intelligent caching of unchanged files
67
- **Configuration System**: Support for both CLI arguments and package.json configuration
68

69
## Capabilities
70

71
### Command Line Interface
72

73
Comprehensive CLI tool with 20+ options for measuring and reporting TypeScript type coverage. Supports thresholds, detailed reporting, caching, and integration with CI/CD pipelines.
74

75
```bash { .api }
76
type-coverage [options] [-- file1.ts file2.ts ...]
77
```
78

79
Key CLI options:
80
```bash { .api }
81
-p, --project <string>          Path to tsconfig.json
82
--at-least <number>            Fail if coverage < this value
83
--detail                       Show detailed results
84
--strict                       Enable strict mode checking
85
--cache                        Enable result caching
86
--ignore-files <patterns>      Ignore specific files/patterns
87
--json-output                  Output results as JSON
88
```
89

90
[Command Line Interface](./cli.md)
91

92
### Programmatic API
93

94
Core library API for integrating type coverage analysis into custom tools, build systems, and development workflows.
95

96
```typescript { .api }
97
function lint(
98
  project: string, 
99
  options?: Partial<LintOptions>
100
): Promise<{
101
  correctCount: number;
102
  totalCount: number;
103
  anys: AnyInfo[];
104
  program: ts.Program;
105
  fileCounts: Map<string, Pick<FileTypeCheckResult, 'correctCount' | 'totalCount'>>;
106
}>;
107

108
function lintSync(
109
  compilerOptions: ts.CompilerOptions,
110
  rootNames: string[],
111
  options?: Partial<LintOptions>
112
): {
113
  correctCount: number;
114
  totalCount: number;
115
  anys: Array<AnyInfo & { sourceFile: ts.SourceFile }>;
116
  program: ts.Program;
117
  fileCounts: Map<string, Pick<FileTypeCheckResult, 'correctCount' | 'totalCount'>>;
118
};
119

120
interface LintOptions {
121
  debug: boolean;
122
  strict: boolean;
123
  enableCache: boolean;
124
  ignoreFiles?: string | string[];
125
  ignoreCatch: boolean;
126
  ignoreUnreadAnys: boolean;
127
  ignoreNested: boolean;
128
  ignoreAsAssertion: boolean;
129
  ignoreTypeAssertion: boolean;
130
  ignoreNonNullAssertion: boolean;
131
  ignoreObject: boolean;
132
  ignoreEmptyType: boolean;
133
  reportSemanticError: boolean;
134
  reportUnusedIgnore: boolean;
135
  fileCounts: boolean;
136
  files?: string[];
137
  cacheDirectory?: string;
138
  notOnlyInCWD?: boolean;
139
}
140
```
141

142
[Programmatic API](./programmatic-api.md)
143

144
## Types
145

146
```typescript { .api }
147
interface AnyInfo {
148
  file: string;
149
  line: number;
150
  character: number;
151
  text: string;
152
  kind: FileAnyInfoKind;
153
}
154

155
interface FileTypeCheckResult {
156
  correctCount: number;
157
  totalCount: number;
158
  anys: FileAnyInfo[];
159
}
160

161
interface FileAnyInfo {
162
  line: number;
163
  character: number;
164
  text: string;
165
  kind: FileAnyInfoKind;
166
}
167

168
enum FileAnyInfoKind {
169
  any = 1,                    // any type
170
  containsAny = 2,           // Promise<any>
171
  unsafeAs = 3,              // foo as string
172
  unsafeTypeAssertion = 4,   // <string>foo
173
  unsafeNonNull = 5,         // foo!
174
  semanticError = 6,         // TypeScript semantic errors
175
  unusedIgnore = 7           // Unused ignore directives
176
}
177
```