Report fatal parsing errors differently than standard errors

eslint v7.9.0

We have eslint integrated in our CI/CD pipelines and we would like to distinguish between cases when linting was successful and when linting failed due to fatal errors during parsing. Such errors are often caused by misconfigured parser or by trying to lint files with syntax errors.

Sample error:

{
    "ruleId": null,
    "fatal": true,
    "severity": 2,
    "message": "Parsing error: 'import' and 'export' may appear only with 'sourceType: module'",
    "line": 1,
    "column": 1
}

We see such cases as unsuccessful linting and would like to propose exiting with exit code 2. This seems in line with what can be read in the Exit codes docs:

When linting files, ESLint will exit with one of the following exit codes:

0: Linting was successful and there are no linting errors. If the --max-warnings flag is set to n, the number of linting warnings is at most n. 1: Linting was successful and there is at least one linting error, or there are more linting warnings than allowed by the --max-warnings option. 2: Linting was unsuccessful due to a configuration problem or an internal error.

If eslint starts returning 2 we could fail early in the pipeline without parsing the result files (which we do only in later stages) and let the user know that linting was actually not successful and configs need to be changed (e.g. update parser options or ignore invalid files).

Alternatively, we could consider introducing new exit code 3 that would cover just this case.

Can you please review the proposal and let us know? We might have capacity for contribution but we would like to agree on the approach first. Thanks.

[mdjermanovic]

I think --max-fatal-errors would be confusing for users.

It has a similar name as --max-warnings, but --max-warnings makes a difference between success and failure while --max-fatal-errors only changes the severity of a failure. I’d expect exit code 0 when there are no more than max fatal errors.

Maybe we could add a boolean option instead of a threshold number?

Also, 3 usually indicates a more severe error than 2, while this is at most equal to scenarios that produce exit code 2, so the same exit code 2 might make more sense than introducing a new exit code 3?

[nzakas]

Thanks for the suggestion. I don’t think we can change the meaning of exit code 2 at this point, as that would be fairly unexpected to a lot of systems. Right now 2 effectively means ESLint crashed and changing that has consequences.

Adding a 3 that is less severe than 2 also doesn’t seem like a good idea.

An alternative approach could be to add a command line option so you could opt-in to the behavior you’re describing. I’m not opposed to something like that as I think reporting parsing errors in a different way can make sense in some situations.

Just FYI: a proposal like this would need to go through our RFC process, and I’d wait for more feedback from the team before starting that.