Provide documentation for writing eslint rules in typescript

[johnwiseheart]

Currently theres a bunch of rules at https://github.com/bradzacher/eslint-plugin-typescript written in js that, since they're operating on typescript should eventually be migrated to be written in typescript as per the comment https://github.com/bradzacher/eslint-plugin-typescript/issues/56#issuecomment-455313509.

I think a good first step here would be to:

1. Figure out how the typing works for writing rules in typescript - I still haven't gotten my head around where all the types come from since some are from ESTree, some are from the JSX spec, and then some will be typescript specific

2. Create or update ESUtils to be typescript so that it can provide typeguards as helper functions - for example isJSXAttribute(node), similar to how https://github.com/ajafff/tsutils works at the moment.

[johnwiseheart]

If folks have any ideas on the first point, feel free to shout out.

From what I could tell, theres ESTree which provides ESTree.Node, but doesn't have the addition of the JSX spec, so doesn't include any nodes like JSXAttribute which ideally would be available in the TSUtils-style helper library.

Perhaps we need to create these types? Ideally they would be usable in conjunction with the ESTree types, so that rules can be written in typescript without needing to use the ts nodes.

[armano2]

https://github.com/armano2/typescript-eslint/blob/es-tree-nodes/packages/typescript-estree/src/es-tree-nodes.ts

i started working on this some time ago, this is ast generated from parser

but it's going to take some time to finish, and right now we have migrations :>

[johnwiseheart]

Thats awesome! Yeah obviously it makes sense to get the migrations done first - but this gives a good starting point for future work. Once the migrations are done, happy to help finish these off and get started on a utils package.

[adidahiya]

I see that the eslint-plugin package got migrated to TS, but I think we still need some docs that go beyond the main ESLint rule development docs... with some information about node types in @typescript-eslint/typescript-estree, type guards, etc.

Should these docs be written as markdown files in https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/typescript-estree/src ?

[bradzacher]

They would probably be better suited to being in the plugin project folder.
At least if I was a new contributor looking to dive into writing a rule, I wouldn't go look at docs in a separate project unless I needed to understand that project first.

It'd probably be good to outline what we'd want to see in the docs.

I can think of a few things:

• Selectors
• Fixers
• Type guards (Using AST_NODE_TYPES, using 'prop' in node...)

[j-f1]

I had to create a file with a copy of some of the type information from this project to get this to work.

[johnwiseheart]

It has been a fair while since I opened this issue, and the project has come a long way. I think one thing that would be valuable is to create an example repo or yeomen generator (or similar) with a rule or two written in typescript. This would give a clear understanding of:

1. Where do I import specific tooling from (@typescript-eslint/experimental-utils)?
2. How do I write a simple lint rule?
3. How do I write tests for it?

The complexity of the current layout of the repo means it's hard to track down which things are called where, and how simple things like testing work.

[bradzacher]

Documentation is something we need to work on as a whole (eg #1298).

I just haven't had a lot of spare time outside of general triaging, reviews and bugfixes.
I've prioritised that work over documentation, because people are generally cluey enough to persevere past and overcome the crappy onboarding experience, so there is a lot more tangible impact for end users in fixing bugs and adding requested features.

Similarly for people using experimental-utils to build eslint rules in TS, I didn't think people did it that much... I'm very surprised that there are actually so many projects (some 35 odd) have figured out how use experimental-utils: https://www.npmjs.com/browse/depended/@typescript-eslint/experimental-utils

But the same argument stands - time spent on documentation for creating an eslint plugin with TS, is "much lower impact".

It's not that I don't want to - it's that I have a limited amount of time to volunteer (5-10 hours a week). I'm still figuring out how to best divvy up my time.

Contributors are always onboarded already, so they would rather fix bugs blocking them, or add features they need, rather than contributing docs for others...
It's a chicken and egg problem. Once there are docs, people will probably contribute to improving them, but nobody wants to create the first cut.

I'll see if I can spend some time this month on it all. I'm on PTO from work, so I've got a bit more time on my hands.

[johnwiseheart]

Yep, that all makes sense - and I expect I'll feel much the same once I'm onboarded 😆

Once I figure things out, happy to make a demo repo with a simple rule and test if that is helpful!

[jens-morten-mikkelsen]

I am a little curious, I have been trying to write my own rules using typescript for a while now, but cant find any docs other than: https://github.com/typescript-eslint/typescript-eslint/blob/master/docs/getting-started/plugin-development/README.md

So I was wondering what is the status on docs for writing rules? 😄

[rhyek]

If anyone had a link to a working repo that would be a great help, as well. I feel completely blocked on writing a simple rule that checks for type information when this was pretty straightforward using TSLint.

[bradzacher]

For now - this repo itself serves as documentation in the form of examples.
https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/eslint-plugin

There are no other docs right now, as I haven't had the time to write any and nobody in the community has stepped up to write some. (as I mentioned in #40 (comment) - once onboarded, people don't feel the drive to contribute docs back)

I wish I could help out, but I just don't have a spare few hours to sit down and write some docs, as all my volunteer time is spent on issues/prs.