0
# Result Reporting
1

2
Reporter system for collecting, managing, and accessing linting results with severity levels and structured output. The Reporter class is the central mechanism for gathering and organizing linting issues found during code analysis.
3

4
## Capabilities
5

6
### Reporter Class
7

8
Main class for collecting and managing linting results during code analysis.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Reporter instance for collecting linting results
13
 * @param {Array} tokens - Array of parsed tokens from source code
14
 * @param {Object} config - Configuration object with rules
15
 */
16
class Reporter {
17
  constructor(tokens, config);
18
}
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const Reporter = require('solhint/lib/reporter');
25

26
// Create reporter instance
27
const tokens = []; // From parser
28
const config = { rules: { 'func-visibility': 'error' } };
29
const reporter = new Reporter(tokens, config);
30

31
// Reporter is typically created internally by processing functions
32
const { processStr } = require('solhint');
33
const report = processStr('contract Test {}'); // Returns Reporter instance
34
```
35

36
### Add Report
37

38
Adds a linting report/issue with specific location and severity information.
39

40
```javascript { .api }
41
/**
42
 * Adds a linting report/issue
43
 * @param {number} line - Line number where issue occurs
44
 * @param {number} column - Column number where issue occurs  
45
 * @param {number} severity - Severity level (Reporter.SEVERITY.ERROR or Reporter.SEVERITY.WARN)
46
 * @param {string} message - Description of the issue
47
 * @param {string} ruleId - Identifier of the rule that triggered this report
48
 * @param {Function} fix - Optional fix function for auto-fixing (optional)
49
 */
50
addReport(line, column, severity, message, ruleId, fix);
51
```
52

53
**Usage Examples:**
54

55
```javascript
56
// Add error report
57
reporter.addReport(
58
  10, 
59
  5, 
60
  Reporter.SEVERITY.ERROR, 
61
  'Function visibility must be declared', 
62
  'func-visibility'
63
);
64

65
// Add warning with fix function
66
reporter.addReport(
67
  15,
68
  8,
69
  Reporter.SEVERITY.WARN,
70
  'Variable name should be in mixedCase',
71
  'var-name-mixedcase',
72
  (fixer) => fixer.replaceText(node, 'correctedName')
73
);
74
```
75

76
### Add Message
77

78
Adds a message using AST location object for automatic line/column extraction.
79

80
```javascript { .api }
81
/**
82
 * Adds a message using AST location object
83
 * @param {Object} loc - AST location object with start/end properties
84
 * @param {number} defaultSeverity - Default severity level if not configured
85
 * @param {string} message - Description of the issue
86
 * @param {string} ruleId - Identifier of the rule
87
 * @param {Function} fix - Optional fix function (optional)
88
 */
89
addMessage(loc, defaultSeverity, message, ruleId, fix);
90
```
91

92
### Add Message Explicit Line
93

94
Adds a message with explicit line and column numbers, applying rule configuration and comment directive checks.
95

96
```javascript { .api }
97
/**
98
 * Adds a message with explicit line and column numbers
99
 * @param {number} line - Line number where issue occurs
100
 * @param {number} column - Column number where issue occurs
101
 * @param {number} defaultSeverity - Default severity level if not configured
102
 * @param {string} message - Description of the issue
103
 * @param {string} ruleId - Identifier of the rule
104
 * @param {Function} fix - Optional fix function (optional)
105
 */
106
addMessageExplicitLine(line, column, defaultSeverity, message, ruleId, fix);
107
```
108

109
**Usage Examples:**
110

111
```javascript
112
// Using AST node location
113
const astNode = {
114
  loc: {
115
    start: { line: 12, column: 4 },
116
    end: { line: 12, column: 20 }
117
  }
118
};
119

120
reporter.addMessage(
121
  astNode.loc,
122
  Reporter.SEVERITY.ERROR,
123
  'Avoid using low level calls',
124
  'avoid-low-level-calls'
125
);
126
```
127

128
### Error Method
129

130
Convenience method for adding error-level reports using AST context.
131

132
```javascript { .api }
133
/**
134
 * Adds an error-level report
135
 * @param {Object} ctx - AST context object with location information
136
 * @param {string} ruleId - Rule identifier
137
 * @param {string} message - Error message
138
 * @param {Function} fix - Optional fix function (optional)
139
 */
140
error(ctx, ruleId, message, fix);
141
```
142

143
### Warn Method
144

145
Convenience method for adding warning-level reports using AST context.
146

147
```javascript { .api }
148
/**
149
 * Adds a warning-level report
150
 * @param {Object} ctx - AST context object with location information
151
 * @param {string} ruleId - Rule identifier
152
 * @param {string} message - Warning message
153
 * @param {Function} fix - Optional fix function (optional)
154
 */
155
warn(ctx, ruleId, message, fix);
156
```
157

158
### Error At
159

160
Convenience method for adding error-level reports at specific line and column.
161

162
```javascript { .api }
163
/**
164
 * Adds an error-level report at specific location
165
 * @param {number} line - Line number where error occurs
166
 * @param {number} column - Column number where error occurs
167
 * @param {string} ruleId - Rule identifier
168
 * @param {string} message - Error message
169
 */
170
errorAt(line, column, ruleId, message);
171
```
172

173
**Usage Examples:**
174

175
```javascript
176
// In a rule implementation
177
class MyRule {
178
  visitFunctionDefinition(node) {
179
    if (node.visibility === null) {
180
      this.reporter.error(
181
        node,
182
        'func-visibility',
183
        'Function visibility must be declared'
184
      );
185
    }
186
    
187
    if (node.name.startsWith('_') && node.visibility === 'public') {
188
      this.reporter.warn(
189
        node,
190
        'private-vars-leading-underscore',
191
        'Public functions should not start with underscore'
192
      );
193
    }
194
  }
195
}
196
```
197

198
### Error Count
199

200
Returns the count of error-level reports.
201

202
```javascript { .api }
203
/**
204
 * Returns count of error-level reports
205
 * @returns {number} Number of errors
206
 */
207
get errorCount();
208
```
209

210
### Warning Count
211

212
Returns the count of warning-level reports.
213

214
```javascript { .api }
215
/**
216
 * Returns count of warning-level reports
217
 * @returns {number} Number of warnings
218
 */
219
get warningCount();
220
```
221

222
### Messages
223

224
Returns sorted array of all reports by line number.
225

226
```javascript { .api }
227
/**
228
 * Returns sorted array of all reports
229
 * @returns {Array<Object>} Array of report objects sorted by line number
230
 */
231
get messages();
232
```
233

234
### File Path
235

236
Returns the file path being reported on.
237

238
```javascript { .api }
239
/**
240
 * Returns the file path being reported on
241
 * @returns {string} File path
242
 */
243
get filePath();
244
```
245

246
**Usage Examples:**
247

248
```javascript
249
const { processFile } = require('solhint');
250

251
const report = processFile('./contracts/Token.sol');
252

253
// Check results
254
console.log(`File: ${report.filePath}`);
255
console.log(`Errors: ${report.errorCount}`);
256
console.log(`Warnings: ${report.warningCount}`);
257

258
// Process all messages
259
report.messages.forEach(msg => {
260
  const severity = msg.severity === Reporter.SEVERITY.ERROR ? 'ERROR' : 'WARN';
261
  console.log(`${severity} at line ${msg.line}: ${msg.message} (${msg.ruleId})`);
262
});
263

264
// Check if file has any issues
265
if (report.errorCount > 0) {
266
  console.log('File has errors that must be fixed');
267
  process.exit(1);
268
}
269

270
if (report.warningCount > 0) {
271
  console.log('File has warnings that should be addressed');
272
}
273
```
274

275
## Report Object Structure
276

277
Each report in the `messages` array has the following structure:
278

279
```javascript { .api }
280
interface LintingReport {
281
  line: number;        // Line number (1-based)
282
  column: number;      // Column number (1-based, adjusted by +1)
283
  severity: number;    // SEVERITY.ERROR (2) or SEVERITY.WARN (3)
284
  message: string;     // Human-readable description
285
  ruleId: string;      // Rule identifier (e.g., 'func-visibility')
286
  fix?: Function;      // Optional fix function for auto-fixing
287
}
288
```
289

290
## Severity Levels
291

292
```javascript { .api }
293
const SEVERITY = {
294
  ERROR: 2,    // Critical issues that should block deployment
295
  WARN: 3      // Style issues and recommendations
296
};
297
```
298

299
**Usage Examples:**
300

301
```javascript
302
// Check severity levels
303
report.messages.forEach(msg => {
304
  if (msg.severity === Reporter.SEVERITY.ERROR) {
305
    console.error(`CRITICAL: ${msg.message}`);
306
  } else if (msg.severity === Reporter.SEVERITY.WARN) {
307
    console.warn(`WARNING: ${msg.message}`);
308
  }
309
});
310
```
311

312
## Configuration Integration
313

314
The Reporter respects rule configuration for severity levels:
315

316
- Rules can be configured as 'error', 'warn', or 'off'
317
- Array configuration: `['error', ...options]` where first element is severity
318
- Comment directives can disable rules inline: `// solhint-disable-next-line rule-name`
319

320
**Configuration Examples:**
321

322
```javascript
323
const config = {
324
  rules: {
325
    'func-visibility': 'error',           // Always error
326
    'max-line-length': ['warn', 120],     // Warning with option
327
    'no-console': 'off'                   // Disabled
328
  }
329
};
330
```
331

332
## Auto-fixing Support
333

334
Reports can include fix functions for automatic code correction:
335

336
```javascript
337
// Fix function example
338
const fix = (fixer) => {
339
  return fixer.replaceText(node, 'public');
340
};
341

342
reporter.addReport(line, col, severity, message, ruleId, fix);
343
```
344

345
Fix functions work with the RuleFixer system to modify source code safely.