0
# Semistandard
1

2
Semistandard is a JavaScript linting tool that enforces JavaScript Standard Style rules with the addition of mandatory semicolons. Built on top of ESLint and the standard-engine, it provides both a command-line interface and a programmatic API for checking code style compliance in JavaScript projects.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
import semistandard from "semistandard";
15
```
16

17
For CommonJS (legacy support):
18

19
```javascript
20
const semistandard = require("semistandard");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import semistandard from "semistandard";
27

28
// Lint files
29
const results = await semistandard.lintFiles(["src/**/*.js"]);
30

31
// Lint source code text
32
const results = await semistandard.lintText('console.log("hello")\n');
33

34
// Check results
35
results.forEach(result => {
36
  if (result.errorCount > 0) {
37
    console.log(`Errors in ${result.filePath}:`);
38
    result.messages.forEach(msg => {
39
      console.log(`  ${msg.message}`);
40
    });
41
  }
42
});
43
```
44

45
## Capabilities
46

47
### File Linting
48

49
Lints JavaScript files matching the provided file paths or glob patterns.
50

51
```javascript { .api }
52
/**
53
 * Asynchronously lints files matching the provided file paths/globs
54
 * @param files - Array of file paths or glob patterns to lint
55
 * @param opts - Optional linting configuration options
56
 * @returns Promise resolving to array of lint results
57
 */
58
async function lintFiles(files: string[], opts?: LintOptions): Promise<LintResult[]>;
59
```
60

61
**Usage Examples:**
62

63
```javascript
64
import semistandard from "semistandard";
65

66
// Lint specific files
67
const results = await semistandard.lintFiles(["index.js", "lib/utils.js"]);
68

69
// Lint with glob patterns
70
const results = await semistandard.lintFiles(["src/**/*.js", "test/*.js"]);
71

72
// With options
73
const results = await semistandard.lintFiles(["src/**/*.js"], {
74
  cwd: "/path/to/project",
75
  fix: true
76
});
77
```
78

79
### Text Linting
80

81
Lints provided source code text directly without file system access.
82

83
```javascript { .api }
84
/**
85
 * Asynchronously lints provided source code text
86
 * @param text - Source code text to lint
87
 * @param opts - Optional linting configuration options  
88
 * @returns Promise resolving to array of lint results
89
 */
90
async function lintText(text: string, opts?: LintOptions): Promise<LintResult[]>;
91
```
92

93
**Usage Examples:**
94

95
```javascript
96
import semistandard from "semistandard";
97

98
// Lint source code string
99
const code = 'console.log("hello world")\n';
100
const results = await semistandard.lintText(code);
101

102
// With filename for better error reporting
103
const results = await semistandard.lintText(code, {
104
  filename: "example.js"
105
});
106
```
107

108
### Command Line Interface
109

110
Global installation provides the `semistandard` command for terminal usage.
111

112
```bash
113
# Install globally
114
npm install -g semistandard
115

116
# Lint files
117
semistandard src/**/*.js
118

119
# Auto-fix issues
120
semistandard --fix src/**/*.js
121

122
# Verbose output
123
semistandard --verbose src/**/*.js
124
```
125

126
## Types
127

128
```javascript { .api }
129
interface LintResult {
130
  /** Number of errors found in the file/text */
131
  errorCount: number;
132
  /** Number of warnings found in the file/text */
133
  warningCount: number;
134
  /** File path (only present for lintFiles results) */
135
  filePath?: string;
136
  /** Array of lint messages */
137
  messages: LintMessage[];
138
  /** Fixed source code (only present when fix: true option is used) */
139
  output?: string;
140
}
141

142
interface LintMessage {
143
  /** Description of the lint issue */
144
  message: string;
145
  /** Line number where issue occurs */
146
  line: number;
147
  /** Column number where issue occurs */
148
  column: number;
149
  /** Rule that triggered the message */
150
  ruleId: string;
151
  /** Severity level (1 = warning, 2 = error) */
152
  severity: number;
153
}
154

155
interface LintOptions {
156
  /** Current working directory for resolving files */
157
  cwd?: string;
158
  /** Automatically fix fixable issues */
159
  fix?: boolean;
160
  /** File extensions to lint (default: ['.js']) */
161
  extensions?: string[];
162
  /** Filename to use for error reporting (lintText only) */
163
  filename?: string;
164
  /** Global variables to define */
165
  globals?: string[];
166
  /** Files/patterns to ignore */
167
  ignore?: string[];
168
  /** Custom parser to use (e.g., 'babel-eslint') */
169
  parser?: string;
170
  /** Plugins to enable */
171
  plugins?: string[];
172
}
173
```
174

175
## Configuration
176

177
### Package.json Integration
178

179
```json
180
{
181
  "scripts": {
182
    "lint": "semistandard",
183
    "lint:fix": "semistandard --fix",
184
    "test": "semistandard && node test.js"
185
  },
186
  "semistandard": {
187
    "ignore": [
188
      "build/**",
189
      "dist/**", 
190
      "tmp.js"
191
    ],
192
    "parser": "babel-eslint",
193
    "globals": ["describe", "it", "before", "after"]
194
  }
195
}
196
```
197

198
### Custom Parser Support
199

200
For projects using advanced JavaScript features or TypeScript:
201

202
```json
203
{
204
  "semistandard": {
205
    "parser": "babel-eslint"
206
  }
207
}
208
```
209

210
### Ignore Patterns
211

212
Files automatically ignored:
213
- `node_modules/**`
214
- `*.min.js`
215
- `bundle.js`
216
- `coverage/**`
217
- Hidden files/folders (starting with `.`)
218
- All patterns in `.gitignore`
219

220
Additional patterns can be specified:
221

222
```json
223
{
224
  "semistandard": {
225
    "ignore": [
226
      "**/build/",
227
      "/lib/vendor/",
228
      "generated.js"
229
    ]
230
  }
231
}
232
```
233

234
## Editor Integration
235

236
### Visual Studio Code
237
Install the [vscode-standardjs](https://marketplace.visualstudio.com/items?itemName=chenxsan.vscode-standardjs) extension.
238

239
### Sublime Text
240
Use [SublimeLinter-contrib-semistandard](https://github.com/Flet/SublimeLinter-contrib-semistandard).
241

242
### Vim
243
Install Syntastic and configure:
244

245
```vim
246
let g:syntastic_javascript_checkers=['standard']
247
let g:syntastic_javascript_standard_exec = 'semistandard'
248
```
249

250
For auto-fix on save:
251

252
```vim
253
autocmd bufwritepost *.js silent !semistandard % --fix
254
set autoread
255
```
256

257
## Rules
258

259
Semistandard enforces all [JavaScript Standard Style](https://github.com/standard/standard) rules with one key difference:
260

261
- **Mandatory semicolons** - All statements must end with semicolons
262
- All other Standard Style rules apply (2-space indentation, single quotes, etc.)
263

264
Common violations detected:
265
- Missing semicolons: `console.log('hello')` → `console.log('hello');`
266
- Double quotes: `"hello"` → `'hello'`
267
- Wrong indentation: 4 spaces → 2 spaces
268
- Trailing whitespace
269
- Mixed operators without parentheses
270

271
## Error Handling
272

273
Both `lintFiles` and `lintText` return arrays of results rather than throwing errors. Check the `errorCount` property and `messages` array to handle lint violations:
274

275
```javascript
276
const results = await semistandard.lintFiles(['src/app.js']);
277

278
results.forEach(result => {
279
  if (result.errorCount > 0) {
280
    console.error(`Found ${result.errorCount} errors in ${result.filePath}:`);
281
    result.messages.forEach(msg => {
282
      console.error(`  Line ${msg.line}: ${msg.message}`);
283
    });
284
    process.exit(1);
285
  }
286
});
287
```