0
# ts-standard
1

2
ts-standard is a TypeScript linting tool that provides StandardJS-style linting for TypeScript projects. It combines ESLint with TypeScript-specific configurations to automatically check and fix TypeScript code according to the Standard Style guidelines, offering a zero-configuration alternative to manually setting up ESLint with TypeScript configurations.
3

4
## Package Information
5

6
- **Package Name**: ts-standard
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install --save-dev ts-standard`
10

11
## Core Imports
12

13
```javascript
14
import tsStandard from "ts-standard";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const tsStandard = require("ts-standard");
21
```
22

23

24
## Basic Usage
25

26
### Programmatic API
27

28
```javascript
29
import tsStandard from "ts-standard";
30

31
// Lint multiple files
32
const results = await tsStandard.lintFiles(['src/**/*.ts', 'src/**/*.js']);
33
console.log(results[0].errorCount); // Number of errors found
34

35
// Lint text directly
36
const [result] = await tsStandard.lintText('console.log("hello world")');
37
console.log(result.errorCount); // Will be 1 due to double quotes (should use single)
38
```
39

40
### Command Line Interface
41

42
```bash
43
# Basic usage - lint all TypeScript/JavaScript files
44
ts-standard
45

46
# Automatically fix problems  
47
ts-standard --fix
48

49
# Specify TypeScript config location
50
ts-standard --project ./tsconfig.eslint.json
51

52
# Show help
53
ts-standard --help
54

55
# Show version
56
ts-standard --version
57
```
58

59
## Capabilities  
60

61
### Programmatic Linting Engine
62

63
The main export provides a pre-configured StandardEngine instance for programmatic use.
64

65
```javascript { .api }
66
// Default export - pre-configured StandardEngine instance
67
declare const tsStandard: StandardEngine;
68
export default tsStandard;
69

70
interface StandardEngine {
71
  /**
72
   * Lint multiple files and return results
73
   * @param files - Array of file paths or glob patterns to lint
74
   * @returns Promise resolving to array of lint results
75
   */
76
  lintFiles(files: string[]): Promise<LintResult[]>;
77

78
  /**
79
   * Lint text content directly and return results
80
   * @param code - Source code string to lint
81
   * @param options - Optional configuration for linting
82
   * @returns Promise resolving to array containing single lint result
83
   */
84
  lintText(code: string, options?: { filename?: string }): Promise<LintResult[]>;
85
}
86

87
interface LintResult {
88
  /** Number of errors found in the linted code */
89
  errorCount: number;
90
  /** Number of warnings found in the linted code */
91
  warningCount: number;
92
  /** Array of specific lint messages */
93
  messages: LintMessage[];
94
  /** File path (when linting files) */
95
  filePath?: string;
96
}
97

98
interface LintMessage {
99
  /** Line number where issue occurs */
100
  line: number;
101
  /** Column number where issue occurs */
102
  column: number;
103
  /** Severity level (1 = warning, 2 = error) */
104
  severity: number;
105
  /** Human-readable error message */
106
  message: string;
107
  /** ESLint rule identifier */
108
  ruleId: string | null;
109
}
110
```
111

112
The engine is pre-configured with:
113
- TypeScript parser options (@typescript-eslint/parser)
114
- ESLint configuration extending "standard-with-typescript" and "standard-jsx"  
115
- Automatically resolved TypeScript configuration file path
116
- Default file extensions: js, jsx, mjs, cjs, ts, tsx
117

118
### Command Line Interface
119

120
Complete command-line interface for linting TypeScript projects.
121

122
**Basic Flags:**
123
- `--fix`: Automatically fix problems
124
- `-p, --project`: Specify ts-config location (default: ./tsconfig.eslint.json or ./tsconfig.json)
125
- `--version`: Show current version
126
- `-h, --help`: Show usage information
127

128
**Advanced Flags:**
129
- `--stdin`: Read file text from stdin
130
- `--ext`: Specify JavaScript/TypeScript file extensions
131
- `--global`: Declare global variable
132
- `--plugin`: Use custom eslint plugin
133
- `--env`: Use custom eslint environment
134
- `--parser`: Use custom ts/js parser (default: @typescript-eslint/parser)
135

136
### TypeScript Configuration Resolution
137

138
ts-standard automatically discovers and resolves TypeScript configuration files. The configuration resolution follows this priority:
139

140
1. CLI `--project` flag value
141
2. `ts-standard.project` in package.json
142
3. `tsconfig.eslint.json` in current directory
143
4. `tsconfig.json` in current directory
144

145
## Configuration
146

147
### Package.json Configuration
148

149
You can configure ts-standard behavior in your package.json:
150

151
```json
152
{
153
  "ts-standard": {
154
    "project": "path/to/tsconfig.json",
155
    "ignore": [
156
      "dist",
157
      "src/**/*.js"
158
    ]
159
  }
160
}
161
```
162

163
### TypeScript Configuration Requirements
164

165
ts-standard requires a TypeScript configuration file to function properly. It searches for:
166

167
1. `tsconfig.eslint.json` (preferred for linting-specific config)
168
2. `tsconfig.json` (fallback)
169

170
The configuration file should include the files you want to lint and exclude files you want to ignore.
171

172
### ESLint Configuration
173

174
ts-standard uses a pre-configured ESLint setup that extends:
175
- `standard-with-typescript`: TypeScript-specific Standard rules
176
- `standard-jsx`: JSX support for React components
177

178
The ESLint configuration cannot be customized - this is by design to maintain the "zero configuration" philosophy of StandardJS.
179

180
## File Processing
181

182
ts-standard automatically processes these file types:
183
- `.js` - JavaScript files
184
- `.jsx` - React JavaScript files  
185
- `.mjs` - ES module JavaScript files
186
- `.cjs` - CommonJS JavaScript files
187
- `.ts` - TypeScript files
188
- `.tsx` - React TypeScript files
189

190
Automatically ignored paths:
191
- `node_modules/`
192
- `coverage/`
193
- `vendor/`
194
- `*.min.js`
195
- Files/folders beginning with `.` (like `.git/`)
196
- Paths in project's root `.gitignore` file
197

198
## Error Handling
199

200
ts-standard will exit with non-zero status codes when issues are encountered:
201

202
- **Exit code 1**: Linting errors found (and --fix not used or unable to fix all issues)
203
- **Exit code 1**: Unable to locate TypeScript configuration file (tsconfig.json or tsconfig.eslint.json)
204
- **Exit code 0**: No errors found or all errors successfully fixed with --fix flag
205

206
Common error scenarios:
207
- Missing TypeScript configuration file - ts-standard requires a tsconfig.json or tsconfig.eslint.json
208
- Invalid TypeScript configuration - malformed or inaccessible tsconfig file
209
- Linting violations - code that doesn't conform to Standard TypeScript style
210

211