Add support for /*#__PURE__*/ comments. (#2429)

* Add support for /*#__PURE__*/ comments.

* Review comments: Extract and stream-line code, add edge-case test

* Perf optimization for pure annotation comment detection

* Cosmetic name improvements, fix acorn walker import

* Handle new expressions and add simple tests from UglifyJS

* Test advanced scenarios and fix walker type bug

* Make sure annotations are removed together with the annotated nodes even
if this is not covered by normal comment removal.

* Slightly simplify comment handling as I do not expect us to want to iterate
more than once through all comments even if other annotation types
are added

* Add option to deactivate annotations and document it

* Make sure annotations are never handled as a node

* Rename pureAnnotations -> annotations

* Update dependencies

bin/src/help.md

@@ -48,6 +48,7 @@ Basic options:
 --sourcemapExcludeSources   Do not include source code in source maps
 --sourcemapFile <file>      Specify bundle position for source maps
 --no-treeshake              Disable tree-shaking optimisations
+--no-treeshake.annotations  Ignore pure call annotations
 --no-treeshake.propertyReadSideEffects Ignore property access side-effects
 --treeshake.pureExternalModules        Assume side-effect free externals
 

docs/01-command-line-reference.md

@@ -229,6 +229,7 @@ Many options have command line equivalents. In those cases, any arguments passed
 --sourcemapExcludeSources   Do not include source code in source maps
 --sourcemapFile <file>      Specify bundle position for source maps
 --no-treeshake              Disable tree-shaking optimisations
+--no-treeshake.annotations  Ignore pure call annotations
 --no-treeshake.propertyReadSideEffects Ignore property access side-effects
 --treeshake.pureExternalModules        Assume side-effect free externals
 ```

docs/999-big-list-of-options.md

@@ -702,7 +702,7 @@ Default: `false`
 If this option is provided, bundling will not fail if bindings are imported from a file that does not define these bindings. Instead, new variables will be created for these bindings with the value `undefined`.
 
 #### treeshake
-Type: `boolean | { propertyReadSideEffects?: boolean, pureExternalModules?: boolean }`<br>
+Type: `boolean | { propertyReadSideEffects?: boolean, annotations?: boolean, pureExternalModules?: boolean }`<br>
 CLI: `--treeshake`/`--no-treeshake`<br>
 Default: `true`
 
@@ -728,6 +728,25 @@ const result = foo.bar;
 const illegalAccess = foo.quux.tooDeep;
 ```
 
+**treeshake.annotations**<br>
+Type: `boolean`<br>
+CLI: `--treeshake.annotations`/`--no-treeshake.annotations`<br>
+Default: `true`
+
+If `false`, ignore hints from pure annotations, i.e. comments containing `@__PURE__` or `#__PURE__`, when determining side-effects of function calls and constructor invocations. These annotations need to immediately precede the call invocation to take effect. The following code will be completely removed unless this option is set to `false`, in which case it will remain unchanged.
+
+```javascript
+/*@__PURE__*/console.log('side-effect');
+
+class Impure {
+  constructor() {
+    console.log('side-effect')
+  }
+}
+
+/*@__PURE__*/new Impure();
+```
+
 **treeshake.pureExternalModules**<br>
 Type: `boolean`<br>
 CLI: `--treeshake.pureExternalModules`/`--no-treeshake.pureExternalModules`<br>