1 | # Writing formatters
|
2 |
|
3 | A formatter is a function with the following signature:
|
4 |
|
5 | ```js
|
6 | function formatter(results, returnValue) {
|
7 | return 'a string of formatted results';
|
8 | }
|
9 | ```
|
10 |
|
11 | Where the first argument (`results`) is an array of stylelint result objects in the form:
|
12 |
|
13 | ```js
|
14 | // A stylelint result object
|
15 | {
|
16 | source: 'path/to/file.css', // The filepath or PostCSS identifier like <input css 1>
|
17 | errored: true, // This is `true` if at least one rule with an "error"-level severity triggered a warning
|
18 | warnings: [ // Array of rule violation warning objects, each like the following ...
|
19 | {
|
20 | line: 3,
|
21 | column: 12,
|
22 | rule: 'block-no-empty',
|
23 | severity: 'error',
|
24 | text: 'You should not have an empty block (block-no-empty)',
|
25 | },
|
26 | ],
|
27 | deprecations: [ // Array of deprecation warning objects, each like the following ...
|
28 | {
|
29 | text: 'Feature X has been deprecated and will be removed in the next major version.',
|
30 | reference: 'https://stylelint.io/docs/feature-x.md',
|
31 | },
|
32 | ],
|
33 | invalidOptionWarnings: [ // Array of invalid option warning objects, each like the following ...
|
34 | {
|
35 | text: 'Invalid option X for rule Y',
|
36 | },
|
37 | ],
|
38 | ignored: false, // This is `true` if the file's path matches a provided ignore pattern
|
39 | }
|
40 | ```
|
41 |
|
42 | And the second argument (`returnValue`) is an object with one or more of the following keys:
|
43 |
|
44 | ```js
|
45 | {
|
46 | errored: false, // `true` if there were any warnings with "error" severity
|
47 | needlessDisables: [ // Present if stylelint was configured with `reportNeedlessDisables: true`
|
48 | {
|
49 | source: 'path/to/file.css',
|
50 | ranges: [
|
51 | {
|
52 | start: 10,
|
53 | unusedRule: 'indentation',
|
54 | },
|
55 | ],
|
56 | },
|
57 | ],
|
58 | invalidScopeDisables: [ // Present if stylelint was configured with `reportInvalidScopeDisables: true`
|
59 | {
|
60 | source: 'path/to/file.css',
|
61 | ranges: [
|
62 | {
|
63 | start: 1,
|
64 | unusedRule: 'color-named',
|
65 | },
|
66 | ],
|
67 | },
|
68 | ],
|
69 | maxWarningsExceeded: { // Present if stylelint was configured with a `maxWarnings` count
|
70 | maxWarnings: 10,
|
71 | foundWarnings: 15,
|
72 | },
|
73 | }
|
74 | ```
|
75 |
|
76 | ## `stylelint.formatters`
|
77 |
|
78 | stylelint's internal formatters are exposed publicly in `stylelint.formatters`.
|