Hi @fetis. Sorry, I moved on from Angular a few years ago, so I can only forward you to the tests in my rule that I shared here.

thanks for reply anyway

Hi @fetis - I share the same pain at the moment, I managed to write a custom rule for Angular HTML templates, it's auto fixable as well. That's true - there is no sufficient documentation, figuring out things from the source code & guessing was 90% of the job.

Here is a fantastic talk that made it much clearer to me:
https://www.youtube.com/watch?v=JwpGFlkmP74

This article comes in handy as well:
https://fintech.theodo.com/blog-posts/eslint-on-steroids-with-custom-rules

Also, if you use nx, it is much easier to start (you can generate a rule config template). This video is worth watching even if you don't use nx.
https://www.youtube.com/watch?v=tEVNYmJ05Ew

General tips:

• Use https://astexplorer.net/ with the proper parser chosen (@typescript-eslint/parser for TS files or @angular-eslint/template-parser for HTML component template) to inspect your Abstract Syntax Tree. It will allow you to target specific nodes in the rule (more in the videos above)
• It is way easier to create a custom rule for TypeScript files than HTML component templates. Start your adventures with coding custom TS rule
• The best way to test it is to run the lint check command from the terminal. Obviously, any console.log() that you write in the custom ESLint rule code will be displayed in the terminal as well if you need to debug
• IDE may be a little laggy with scanning the files. If you use VS Code press cmd/ctrl + shift + P and type in "Developer: reload window" to refresh the window and test if the code targeted by the rule is reported as an error in the editor.

It is quite simple and not a lot of code if you figure it out - please get in touch with me if you face any problems, it is quite an interesting subject and I would like to explore it more.

I've written a few custom ESLint rules that check Angular templates. Once you have an understanding of the AST, it's really no different to writing an ESLint rule that checks JavaScript or TypeScript.

As @KrystianDerdzinski said, if you're not familiar with writing custom ESLint rules at all, then it's probably best to start with a regular rule that checks JavaScript or TypeScript before taking the extra step to write a rule for Angular templates.

Just in case you haven't seen them, there's some guides for custom rules on the eslint and typescript-eslint websites:

• https://eslint.org/docs/latest/extend/custom-rule-tutorial
• https://eslint.org/docs/latest/extend/custom-rules
• https://typescript-eslint.io/developers/custom-rules

It's also worth understanding ESQuery. It's very powerful and a good selector can reduce the amount of code in the rule.

• https://github.com/estools/esquery

Once you have an understanding of ESLint rules, taking the next step to check Angular templates is quite simple. The way you write the rule is the same - you're just checking a different kind of AST.

Here's a repo that demonstrates a really simple ESLint rule that checks Angular templates for blink elements:

https://github.com/reduckted/eslint-angular-rule-demo

Here are the main differences from a rule that checks JavaScript or TypeScript.

Node names

The node names come from the Angular compiler. As @KrystianDerdzinski mentioned, using https://astexplorer.net/ is an excellent way to understand the AST that represents the HTML from the template. Just be aware that the template parser that it uses is quite old (it's from Angular 14). It still shows the correct AST for most things.

You can find the node names here:

The only one I know of that is not listed there is Text$3. I have no idea where it comes from, nor do I know what the "$3" means (just like I have no idea what the "$1" means in Element$1 🤷‍♂️)

Reporting Problems

When reporting a problem in a normal rule, you would be able to specify the node to report the problem on. Because the rule is working with a different kind of AST, that's not possible. Instead, you can specify the location of the problem. You can convert a node from the AST into a location using the TemplateParserServices.

Testing

Testing is quite simple. Use the repo I linked to above to see how to set up the environment. That repo uses Jest, but you should be able to use any testing framework. I've used Mocha before. It's all just a matter of getting the test runner to work with TypeScript.

Use the RuleTester class from @angular-eslint/test-utils. When you create the RuleTester, you need to tell it to use the parser from @angular-eslint/template-parser so that it can parse the HTML. That's the only special thing you need to do for Angular template rules.

With the RuleTester, you provide it valid code (or HTML in our case) and invalid code. For each invalid test case, you need to provide the expected errors. You can use the convertAnnotatedSourceToFailureCase function from @angular-eslint/test-utils, which makes it easy to specify where the problems should be reported in the code. You don't have to use that though. In the repo I linked above, I've specified the location of the expected errors using line and column numbers.

For example, in the repo above, I specified the invalid test case like this:

{
    code: '<blink></blink>',
    errors: [
        {
            messageId: 'doNotBlink',
            line: 1,
            column: 1,
            endLine: 1,
            endColumn: 8,
        },
    ],
},

But I could also specify it like this:

convertAnnotatedSourceToFailureCase({
    description: 'test',
    annotatedSource: `
        <blink></blink>
        ~~~~~~~
    `,
    messageId: 'doNotBlink',
});

Debugging

This is just a general tip for debugging ESLint rules. If you use VS Code, use the JavaScript Debug Terminal for stepping through your rule. The easiest way to do this is:

1. Create a test with the template that you want to debug your rule with.
2. Set some breakpoints in your rule.
3. Open a JavaScript Debug Terminal.
4. Run the command to execute the tests (for example, npm run test).

VS Code will run the command and attach the debugger to the process. It will then hit your breakpoints in the rule and you can step through it line by line to see what it's doing.

Hope that helps!

The only one I know of that is not listed there is Text$3. I have no idea where it comes from, nor do I know what the "$3" means (just like I have no idea what the "$1" means in Element$1 🤷‍♂️)

Looks like the $number suffix means it was not yet a stable API. See #2320.

"Type X is not assignable to type Y" is usually a sign that you have different versions of the same dependencies. For example, @typescript-eslint/scope-manager and @typescript-eslint/utils are different versions, which means you have two different versions of @typescript-eslint/scope-manager in the dependency tree.