0
# Solhint
1

2
Solhint is a comprehensive linting tool specifically designed for Solidity smart contract development. It offers both security and style guide validations, helping developers identify potential vulnerabilities, enforce coding standards, and improve code quality in Ethereum smart contracts. The tool supports configurable rulesets with recommended defaults, inline comment-based rule configuration, automatic fixing for certain issues, caching for improved performance, and multiple output formats including JSON and SARIF.
3

4
## Package Information
5

6
- **Package Name**: solhint
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install -g solhint`
10

11
## Core Imports
12

13
```javascript
14
const { processStr, processFile, processPath } = require('solhint');
15
```
16

17
For library modules:
18

19
```javascript
20
const { loadConfig, applyExtends } = require('solhint/lib/config/config-file');
21
const Reporter = require('solhint/lib/reporter');
22
```
23

24
## Basic Usage
25

26
### CLI Usage
27

28
```bash
29
# Initialize configuration
30
solhint --init
31

32
# Lint all Solidity files in contracts directory
33
solhint 'contracts/**/*.sol'
34

35
# Lint with specific configuration
36
solhint -c .solhint.json contracts/MyToken.sol
37

38
# Auto-fix issues where possible
39
solhint --fix 'contracts/**/*.sol'
40
```
41

42
### Programmatic Usage
43

44
```javascript
45
const { processStr, processFile } = require('solhint');
46

47
// Process Solidity source code string
48
const sourceCode = 'contract Example { function test() public {} }';
49
const config = { rules: { 'func-visibility': 'error' } };
50
const report = processStr(sourceCode, config, 'Example.sol');
51

52
console.log('Errors:', report.errorCount);
53
console.log('Warnings:', report.warningCount);
54
console.log('Messages:', report.messages);
55

56
// Process a single file
57
const fileReport = processFile('./contracts/Token.sol');
58
console.log('File path:', fileReport.filePath);
59
```
60

61
## Architecture
62

63
Solhint is built around several key components:
64

65
- **Processing Engine**: Core functions (`processStr`, `processFile`, `processPath`) that orchestrate linting workflow
66
- **AST Parser**: Uses `@solidity-parser/parser` to parse Solidity code into Abstract Syntax Trees
67
- **Rule System**: 64+ rules organized into 7 categories (security, naming, best-practices, etc.)
68
- **Reporter**: Collects and manages linting results with severity levels and metadata
69
- **Configuration System**: Hierarchical configuration loading with extends support and rule customization
70
- **Formatter System**: Multiple output formats (stylish, json, table, compact, unix, tap, sarif)
71
- **CLI Interface**: Command-line tool with multiple commands and extensive options
72

73
## Capabilities
74

75
### Core Processing
76

77
Main linting functions for processing Solidity source code at different levels - from strings to files to directory patterns.
78

79
```javascript { .api }
80
function processStr(inputStr, config = {}, fileName = '');
81
function processFile(file, config, rootDir = process.cwd(), explicitConfigPath);
82
function processPath(pattern, config, rootDir = process.cwd(), explicitConfigPath);
83

84
// Cache Management APIs
85
function readCache(cachePath);
86
function writeCache(cachePath, cacheData);  
87
function shouldLint(filePath, content, config, cacheData);
88
function updateCacheEntry(filePath, content, config, cacheData);
89
```
90

91
[Core Processing](./core-processing.md)
92

93
### Result Reporting
94

95
Reporter system for collecting, managing, and accessing linting results with severity levels and structured output.
96

97
```javascript { .api }
98
class Reporter {
99
  constructor(tokens, config);
100
  addReport(line, column, severity, message, ruleId, fix);
101
  error(ctx, ruleId, message, fix);
102
  warn(ctx, ruleId, message, fix);
103
  get errorCount();
104
  get warningCount();
105
  get messages();
106
}
107
```
108

109
[Result Reporting](./result-reporting.md)
110

111
### Configuration Management
112

113
Configuration loading and management system with hierarchical config resolution and rule inheritance.
114

115
```javascript { .api }
116
function loadConfig(configFile);
117
function loadConfigForFile(filePath, rootDir, explicitConfigPath);
118
function applyExtends(config, getter);
119
function validate(config);
120
```
121

122
[Configuration Management](./configuration-management.md)
123

124
### Rules System
125

126
Comprehensive rule system with 64+ rules across 7 categories for security, style, and best practices validation.
127

128
```javascript { .api }
129
function checkers(reporter, configVals, inputSrc, tokens, fileName);
130
```
131

132
[Rules System](./rules-system.md)
133

134
### Output Formatting
135

136
Multiple formatter functions for different output formats and integration needs.
137

138
```javascript { .api }
139
function stylish(reports);
140
function json(reports);
141
function table(reports);
142
function compact(reports);
143
function unix(reports);
144
function tap(reports);
145
function sarif(reports);
146
```
147

148
[Output Formatting](./output-formatting.md)
149

150
### CLI Interface
151

152
Command-line interface with main command and subcommands for various linting operations.
153

154
```bash { .api }
155
solhint [options] <file> [...other_files]
156
solhint stdin [--filename <name>]
157
solhint init-config
158
solhint list-rules
159
```
160

161
[CLI Interface](./cli-interface.md)
162

163
## Types
164

165
```javascript { .api }
166
interface LintingReport {
167
  line: number;
168
  column: number;
169
  severity: number;
170
  message: string;
171
  ruleId: string;
172
  fix?: Function;
173
}
174

175
interface ConfigObject {
176
  rules?: { [ruleId: string]: string | [string, ...any[]] };
177
  extends?: string | string[];
178
  excludedFiles?: string[];
179
  plugins?: string[];
180
  cache?: boolean;
181
  cacheLocation?: string;
182
}
183

184
interface ProcessingResult {
185
  reports: LintingReport[];
186
  file?: string;
187
  filePath?: string;
188
  errorCount: number;
189
  warningCount: number;
190
  messages: LintingReport[];
191
  skipped?: boolean;
192
}
193
```
194

195
## Constants
196

197
```javascript { .api }
198
const SEVERITY = {
199
  ERROR: 2,
200
  WARN: 3
201
};
202

203
const EXIT_CODES = {
204
  OK: 0,
205
  REPORTED_ERRORS: 1,
206
  BAD_OPTIONS: 255
207
};
208
```