Cambrian explosion of comment pragmas

[piscisaureus]

/// <reference lib="worker" />

/// <amd-module />

/** @jsx jsx */

//# sourceMappingURL=main.js.map

// @deno-types="https://deno.land/x/types/react/v16.13.1/react.d.ts"

// deno-lint-ignore-file no-explicit-any no-empty

// deno-fmt-ignore 

"use strict";

[kitsonk]

To give this a bit more context, it was brought up in a core team discussion that there are several different pragmas in code that impact how Deno handles the code, and they very greatly in style and is a bit of a 🗑️ 🔥 .

That being said, Deno only directly controls a handful of them and several of them are quite long standing standards or de facto standards. So personal opinion is that it is largely un-actionable. We could introduce alternative unified syntax, but would still need to maintain legacy syntax to ensure portability and compatibility. The best thing we can do is help to continue to ensure they are well documented and that we try our best to provide intelligence around them in the editor via the Language Server and carefully consider how we create and additional ones ourselves.

Being more specific, the various pragmas:

• TypeScript triple slash directives, created by the TypeScript team. Deno has specifically repurposed one of them. We have syntax highlighting for them in the Language Server, though we need to add full suggestion support.
• The @ts-check, @ts-nocheck, @ts-ignore, @ts-expect-error directives. Created by the TypeScript team, they have various impacts on how files are type checked. Deno does nothing specifically about these other than supporting them.
• The JSX Pragma. Introduced by Babel, adopted by other transpilers, this provide per file configuration of JSX transpilation. Of course some would argue the whole of JSX is a pragma that is unwelcome. 🤷 Deno does nothing specifically different about them than trying to fully support them. There is syntax highlighting in the Language Server and some completion support, but hover support could be better.
• Source Mapping URL - this was introduced by Mozilla and was widely adopted as a de facto standard. Deno does nothing specific here, on the emit, though we still need to handle source map URLs on the acquire better. I think there maybe issues as well with debug support for them.
• Deno Types - This is the one area where we created additional syntax to solve problems around not "magically" trying to resolve type definitions for files. This is fairly well documented and the language server handles them, but does not currently give good completion suggestions, syntax highlighting or hover support. The use cases of why we need a different pragma than the repurposed one have been discussed and exhausted several times over the years, and the documentation makes it clear what use cases and problems they solve. Any alternative syntax would be a breaking change for a lot of code and likely just change for change sake. There is no clear alternative syntax that would "fix" anything IMO.
• The Deno Lint pragma. While specifically introduced by us, they follow well established precedents with other JavaScript linters, like ESLint.
• The Deno format pragma. Again, while introduced by us, they align well to established precedents with other JavaScript formatters like Prettier.
• JavaScript pragmas ("use strict";) were established by TC39 quite a long time ago and are part of ECMAScript. There is only currently the "use strict"; pragma that is part of the specification there is the proposal for "use module";. There have been a few others that have been specific to runtimes, but generally it seems people avoid it.

[lucacasonato]

Not actionable.