Code review notes

type-auto-algorithm.md

@@ -26,19 +26,19 @@ If the source code did not contain an ESM signifier, continue:
 
 If the source code contains any of the following:
 
-- A reference to a global variable named `__filename`, without code defining the variable.
+- A static reference, unguarded by `typeof`, to a global variable named `__filename`, without code defining the variable.
 
-- A reference to a global variable named `__dirname`, without code defining the variable.
+- A static reference, unguarded by `typeof`, to a global variable named `__dirname`, without code defining the variable.
 
-- A reference to a global variable named `require`, without code defining the variable.
+- A static reference, unguarded by `typeof`, to a global variable named `require`, without code defining the variable.
 
-- A reference to a global variable named `module`, without code defining the variable.
+- A static reference, unguarded by `typeof`, to a global variable named `module`, without code defining the variable.
 
-- A reference to a global variable named `exports`, without code defining the variable.
+- A static reference, unguarded by `typeof`, to a global variable named `exports`, without code defining the variable.
 
 Then the file is assumed to be CommonJS. Stop and execute it as CommonJS JavaScript.
 
-There are syntactical elements that are unambiguously part of the _script goal;_ but while all CommonJS files are script goal JavaScript, not all script goal JavaScript files are CommonJS. (For example, script goal JavaScript intended for browsers.) While we could detect syntax that is unambiguously script goal, as opposed to ESM’s module goal, we exclude those signifiers because they don’t necessarily signify CommonJS. Script goal signifiers are also very uncommon, such as the `with` keyword, and are unlikely to appear in user code.
+There are syntactical elements that are unambiguously part of the _Script goal;_ but while all CommonJS files are Script goal JavaScript, not all Script goal JavaScript files are CommonJS. (For example, Script goal JavaScript intended for browsers.) While we could detect syntax that is unambiguously Script goal, as opposed to ESM’s Module goal, we exclude those signifiers because they don’t necessarily signify CommonJS. Script goal signifiers are also very uncommon, such as the `with` keyword, and are unlikely to appear in user code.
 
 Technically, ESM JavaScript initial entry point files can include references to global variables and still be valid ESM JavaScript. An file containing `require('fs');` is valid ESM, for example, though of course it would throw upon evaluation. A file containing `if (require) { /* ... */ }` would evaluate successfully. Because of this, it is impossible to unambiguously detect CommonJS with total certainty; however, the authors of this proposal cannot identify any real-world use cases for an ESM JavaScript initial entry point to reference CommonJS globals. (There is the use case of JavaScript written for transpilation that contains both `import` and `require` statements, but that’s not valid ESM JavaScript.) Unless a significant class of realistic code can be identified that is both valid ESM and uses meaningful references to CommonJS globals, the heuristic of looking for references to CommonJS globals should affirmatively detect all practical CommonJS files. Especially as an opt-in feature, we consider the utility of `--type=auto` to outweigh concerns regarding detecting CommonJS with total certainty.