Skip to content

Commit 47357dd

Browse files
thboopthboop
authored
Document Problem Matcher Commands (#198)
* Add Initial Problem Matcher docs
1 parent a465bf5 commit 47357dd

File tree

2 files changed

+118
-1
lines changed

2 files changed

+118
-1
lines changed

‎docs/commands.md

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,16 @@ function startGroup(name: string): void {}
102102
function endGroup(): void {}
103103
```
104104

105+
### Problem Matchers
106+
Problems matchers can be used to scan a build's output to automatically surface lines to the user that matches the provided pattern. A file path to a .json Problem Matcher must be provided. See [Problem Matchers](problem-matchers.md) for more information on how to define a Problem Matcher.
107+
108+
```bash
109+
echo "::add-matcher::eslint-compact-problem-matcher.json"
110+
echo "::remove-matcher::eslint-compact"
111+
```
112+
113+
`add-matcher` takes a path to a Problem Matcher file
114+
`remove-matcher` removes a Problem Matcher by owner
105115
### Save State
106116

107117
Save state to be used in the corresponding wrapper (finally) post job entry point.
@@ -116,7 +126,7 @@ Finally, there are several commands to emit different levels of log output:
116126

117127
| log level | example usage |
118128
|---|---|
119-
| [debug](https://github.com/actions/toolkit/blob/master/docs/action-debugging.md) | `echo "::debug::My debug message"` |
129+
| [debug](action-debugging.md) | `echo "::debug::My debug message"` |
120130
| warning | `echo "::warning::My warning message"` |
121131
| error | `echo "::error::My error message"` |
122132

‎docs/problem-matchers.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Problem Matchers
2+
Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI. Both [GitHub Annotations](https://developer.github.com/v3/checks/runs/#annotations-object-1) and log file decorations are created when a match is detected.
3+
4+
## Single Line Matchers
5+
6+
Let's consider the ESLint compact output:
7+
```
8+
badFile.js: line 50, col 11, Error - 'myVar' is defined but never used. (no-unused-vars)
9+
```
10+
We can define a problem matcher in json that detects input in that format:
11+
```json
12+
{
13+
"problemMatcher": [
14+
{
15+
"owner": "eslint-compact",
16+
"pattern": [
17+
{
18+
"regexp": "^(.+):\\sline\\s(\\d+),\\scol\\s(\\d+),\\s(Error|Warning|Info)\\s-\\s(.+)\\s\\((.+)\\)$",
19+
"file": 1,
20+
"line": 2,
21+
"column": 3,
22+
"severity": 4,
23+
"message": 5,
24+
"code": 6
25+
}
26+
]
27+
}
28+
]
29+
}
30+
```
31+
32+
The following fields are available for problem matchers:
33+
34+
```
35+
{
36+
owner: An ID field that can be used to remove or replace the problem matcher. **required**
37+
pattern: [
38+
{
39+
regexp: The regex pattern that provides the groups to match against **required**
40+
file: a group number containing the file name
41+
line: a group number containing the line number
42+
column: a group number containing the column information
43+
severity: a group number containing either 'warning' or 'error' case-insensitive. Defaults to `error`
44+
code: a group number containing the error code
45+
message: a group number containing the error message. **required** at least one pattern must set the message
46+
loop: loops until a match is not found, only valid on the last pattern of a multipattern matcher
47+
}
48+
]
49+
}
50+
```
51+
52+
53+
## Multiline Matching
54+
Consider the following output:
55+
```
56+
test.js
57+
1:0 error Missing "use strict" statement strict
58+
5:10 error 'addOne' is defined but never used no-unused-vars
59+
✖ 2 problems (2 errors, 0 warnings)
60+
```
61+
The file name is printed once, yet multiple error lines are printed. The `loop` keyword provides a way to discover multiple errors in outputs.
62+
63+
The eslint-stylish problem matcher defined below catches that output, and creates two annotations from it.
64+
65+
```
66+
{
67+
"problemMatcher": [
68+
{
69+
"owner": "eslint-stylish",
70+
"pattern": [
71+
{
72+
// Matches the 1st line in the output
73+
"regexp": "^([^\\s].*)$",
74+
"file": 1
75+
},
76+
{
77+
// Matches the 2nd and 3rd line in the output
78+
"regexp": "^\\s+(\\d+):(\\d+)\\s+(error|warning|info)\\s+(.*)\\s\\s+(.*)$",
79+
// File is carried through from above, so we definte the rest of the groups
80+
"line": 1,
81+
"column": 2,
82+
"severity": 3,
83+
"message": 4,
84+
"code": 5,
85+
"loop": true
86+
}
87+
]
88+
}
89+
]
90+
}
91+
```
92+
93+
The first pattern matches the `test.js` line and records the file information. This line is not decorated in the UI.
94+
The second pattern loops through the remaining lines with `loop: true` until it fails to find a match, and surfaces these lines prominently in the UI.
95+
96+
## Adding and Removing Problem Matchers
97+
Problem Matchers are enabled and removed via the toolkit [commands](commands.md#problem-matchers).
98+
99+
## Duplicate Problem Matchers
100+
Registering two problem-matchers with the same owner will result in only the problem matcher registered last running.
101+
102+
## Examples
103+
Some of the starter actions are already using problem matchers, for example:
104+
- [setup-node](https://github.com/actions/setup-node/tree/master/.github)
105+
- [setup-python](https://github.com/actions/setup-python/tree/master/.github)
106+
- [setup-go](https://github.com/actions/setup-go/tree/master/.github)
107+
- [setup-dotnet](https://github.com/actions/setup-dotnet/tree/master/.github)

0 commit comments

Comments
 (0)