Feat: Add description flag for cli annotate command.

[cylewaitforit]

Add a --comment flag so when running the annotate command in cli it will append a comment to the line.

For example running

ts-migrating annotate --comment "Migrating to `erasableSyntaxOnly`."

would annotate

// @ts-migrating -- Migrating to `erasableSyntaxOnly`.

[ycmjason]

Thanks for the suggestion!

I’m currently considering whether this functionality fits within the scope of this library. Since most IDEs already allow you to batch-replace comments like // @ts-migrating with something else, it might not be necessary to support this natively.

My main hesitation is that there doesn’t seem to be a widely accepted convention for comments following directives. For instance, Biome uses the format:

// biome-ignore <rule>: <comment>

So it's unclear what format --comment should generate, and whether it would save enough time to justify the additional complexity.

Still, I’ll keep this open to see if others express interest or propose a standardised format.

[cylewaitforit]

Thanks for the response. I think that is fair.

I was most familiar with directive descriptions from eslint which uses the -- separator. https://github.com/eslint/rfcs/blob/main/designs/2019-description-in-directive-comments/README.md

Trying to find the same sort of information for typescript directives I found conflicting examples.

Learning Typescript used the --.
https://www.learningtypescript.com/articles/comment-directives#comment-directive-explanations

Total Typecript used the :.
https://www.totaltypescript.com/concepts/how-to-use-ts-expect-error#including-a-description-with-ts-expect-error

But looking into this further I found that the default format for the allow-with-description rule in typescript-eslint is the @directive: description.
https://typescript-eslint.io/rules/ban-ts-comment/#allow-with-description

So with that additional information I think I would modify my original suggestion to:

ts-migrating annotate --description "Migrating to `erasableSyntaxOnly`."

To create

// @ts-migrating: Migrating to `erasableSyntaxOnly`.

[ycmjason]

@cylewaitforit

Thanks for looking into this! I personally like : most!

Just before we look into implementing this. Can I ask what is the use case for this? Were you thinking to enable and annotate each flag one at a time, and with this you could make note of what is causing which lines to error?

[cylewaitforit]

Can I ask what is the use case for this? Were you thinking to enable and annotate each flag one at a time, and with this you could make note of what is causing which lines to error?

Yes that would be it exactly. When we have used the descriptions for eslint-disable and ts-expect-error it has been helpful to search the code base to find how may existing spots have been grandfathered into the old way. Occasionally the description may be used for other external context things as well, like an issue number to follow the clean up work or a link out to an article on why you wouldn't want to do use the outdated pattern.

[ycmjason]

Hey @cylewaitforit,

Thank you again for proposing this. I really appreciate your idea.

After thinking it over, I feel that this probably doesn’t need to be part of the library itself. For your use case, a simple text replace in your editor (e.g., changing @ts-migrating to @ts-migrating: description) should be quick and effective.

It does add one extra step, but I imagine most users won’t be running ts-migrating annotate very often anyway so this isn't a huge deal in terms of DX.

I’ll leave this issue open in case there are stronger use cases that might justify this change. Hope that makes sense!

[cylewaitforit]

Sounds good, appreciate that you gave it time and thought.