Use @import JSDoc tags for TypeScript >= 5.5

[blutorange]

These are easier to read than the /** @typedef */ workaround, and also take up less space. For each import, a separate @typedef is required.

TypeScript supports /** @import */ since version 5.5, see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html#the-jsdoc-import-tag

I changed it so that it detects the current TypeScript version and uses @typedef for version < 5.5, and @import for versions >= 5.5. Perhaps you could also add an option for which import style to use, but I prefer less options, and @import seems like the proper way if supported. transpileFile has an optional tsVersion argument, which is needed for tests and could also be used by consumers if needed.

[kungfooman]

So nice!

and @import seems like the proper way if supported

Absolutely, the problem with @typedef is also that it's exporting the type by default... meaning that it creates a bunch of errors in these cases: microsoft/TypeScript#46011 (comment)

It was discussed back and forth without any consensus on how @typedef could/should be fixed, so simply adopting the new @import tag seems like a no-brainer. Nice work! 🥇

[futurGH]

Nice, did not realize this had been added! I like the tsVersion checking implementation as well. Much appreciated!