Proposal: enhance no-restricted-syntax to support custom error messages

[vitorbal]

What version are you using?
v3.18.0

What did you do?

/* eslint no-restricted-syntax: ["error", "CallExpression[callee.name='setTimeout'][arguments.length!=2]"] */
setTimeout(() => {}, 100, 'foo');

What happened?
I got the following error message:

  2:1  error  Using 'CallExpression[callee.name='setTimeout'][arguments.length!=2]' is not allowed  no-restricted-syntax

What did you expect to happen?
I would like to be able to provide custom error messages for the syntax patterns I prohibit using no-restricted-syntax. For the example above:

/*
 * eslint no-restricted-syntax: [
 *     "error",
 *     {
 *         "pattern": "CallExpression[callee.name='setTimeout'][arguments.length!=2]",
 *         "message": "invoking setTimeout with more than 2 arguments is not allowed"
 *     }
 * ]
 */
setTimeout(() => {}, 100, 'foo');

Would provide the following error message:

  2:1  error  invoking setTimeout with more than 2 arguments is not allowed  no-restricted-syntax

Rationale
With the release of the AST selectors feature, the no-restricted-syntax rule just got super powerful, which is awesome.
However, when a complex selector is used to prohibit a certain syntax pattern, the error message can be quite cryptic for devs that are not familiar with the AST selectors.

This proposal aims to allow the customization of the error messages for each of the syntax patterns configured for no-restricted-syntax.

This proposal would be backwards compatible, since the rule logic can check if the passed-in option is a string (old format) or an object (new format). For example:

"no-restricted-syntax": [
    "error",
    "WithStatement",
    "FunctionDeclaration[params.length>3]",
    {
        "pattern": "CallExpression[callee.name='setTimeout'][arguments.length!=2]",
        "message": "invoking setTimeout with more than 2 arguments is not allowed"
    }
]    

[not-an-aardvark]

👍

I'd been planning to suggest this as well, and I'm willing to champion it. One bikeshed is that maybe the option should be called selector instead of pattern.

[platinumazure]

Who's championing? If @vitorbal counts as a 👍 or champion as a result of creating this issue, we can accept now 😄

[vitorbal]

I would also be willing champion this, but I guess it doesn't matter 😄
I'm willing to implement it as well, if @not-an-aardvark doesn't mind?

[not-an-aardvark]

This is probably a record for the shortest time ever between when an issue was created and accepted. 🎉

@vitorbal Sure, go for it. I'll assign the issue to you as a champion if you're also implementing it.

[dwelle]

It'd be great if this was implemented for all no-restricted-* rules. In fact, I can see it useful even for other rules, but I'd say custom messages for no-restricted-* rules is the bare minimum.

Related #8315

[vitorbal]

@dwelle thanks for your suggestion, I think that's a good idea! Could you open a separate issue with the proposal to add custom messages to the other no-restricted- rules?

[dwelle]

@vitorbal #8400