feat: support #__NO_SIDE_EFFECTS__ annotation for function declaration (#5024)

* feat: init

* chore: update

* chore: updates

* chore: update

* test: add test for jsdoc

* chore: coverage

* feat: change the anntation to `__NO_SIDE_EFFECTS__`

* chore: coverage

* chore: update suggestions

* docs: add docs

* Slightly clarify wording

---------

Co-authored-by: Lukas Taegert-Atkinson <[email protected]>

Author: antfu

docs/configuration-options/index.md

@@ -2021,7 +2021,11 @@ If you discover a bug caused by the tree-shaking algorithm, please file an issue
 |     CLI: | `--treeshake.annotations`/`--no-treeshake.annotations` |
 | 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.
+If `false`, ignore hints from annotation in comments:
+
+##### `@__PURE__`
+
+Comments containing `@__PURE__` or `#__PURE__` mark a specific function call or constructor invocation as side effect free. That means that Rollup will tree-shake i.e. remove the call unless the return value is used in some code that is not tree-shaken. These annotations need to immediately precede the call invocation to take effect. The following code will be completely tree-shaken unless this option is set to `false`, in which case it will remain unchanged.
 
 ```javascript
 /*@__PURE__*/ console.log('side-effect');
@@ -2035,6 +2039,25 @@ class Impure {
 /*@__PURE__*/ new Impure();
 ```
 
+##### `@__NO_SIDE_EFFECTS__`
+
+Comments containing `@__NO_SIDE_EFFECTS__` or `#__NO_SIDE_EFFECTS__` mark a function declaration itself as side effect free. When a function has been marked as having no side effects, all calls to that function will be considered to be side effect free. The following code will be completely tree-shaken unless this option is set to `false`, in which case it will remain unchanged.
+
+```javascript
+/*@__NO_SIDE_EFFECTS__*/
+function impure() {
+	console.log('side-effect');
+}
+
+/*@__NO_SIDE_EFFECTS__*/
+const impureArrowFn = () => {
+	console.log('side-effect');
+};
+
+impure(); // <-- call will be considered as side effect free
+impureArrowFn(); // <-- call will be considered as side effect free
+```
+
 #### treeshake.correctVarValueBeforeDeclaration
 
 |  |  |

src/Graph.ts

@@ -17,14 +17,14 @@ import type {
 import { PluginDriver } from './utils/PluginDriver';
 import Queue from './utils/Queue';
 import { BuildPhase } from './utils/buildPhase';
+import { addAnnotations } from './utils/commentAnnotations';
 import {
 	error,
 	errorCircularDependency,
 	errorImplicitDependantIsNotIncluded,
 	errorMissingExport
 } from './utils/error';
 import { analyseModuleExecution } from './utils/executionOrder';
-import { addAnnotations } from './utils/pureComments';
 import { getPureFunctions } from './utils/pureFunctions';
 import type { PureFunctions } from './utils/pureFunctions';
 import { timeEnd, timeStart } from './utils/timers';

src/ast/nodes/ArrowFunctionExpression.ts

@@ -38,6 +38,10 @@ export default class ArrowFunctionExpression extends FunctionBase {
 	): boolean {
 		if (super.hasEffectsOnInteractionAtPath(path, interaction, context)) return true;
 		if (interaction.type === INTERACTION_CALLED) {
+			if (this.annotationNoSideEffects) {
+				return false;
+			}
+
 			const { ignore, brokenFlow } = context;
 			context.ignore = {
 				breaks: false,

src/ast/nodes/CallExpression.ts

@@ -1,5 +1,4 @@
 import type MagicString from 'magic-string';
-import type { NormalizedTreeshakingOptions } from '../../rollup/types';
 import { BLANK } from '../../utils/blank';
 import { errorCannotCallNamespace, errorEval } from '../../utils/error';
 import { renderCallArguments } from '../../utils/renderCallArguments';
@@ -57,11 +56,9 @@ export default class CallExpression
 			for (const argument of this.arguments) {
 				if (argument.hasEffects(context)) return true;
 			}
-			if (
-				(this.context.options.treeshake as NormalizedTreeshakingOptions).annotations &&
-				this.annotations
-			)
+			if (this.annotationPure) {
 				return false;
+			}
 			return (
 				this.callee.hasEffects(context) ||
 				this.callee.hasEffectsOnInteractionAtPath(EMPTY_PATH, this.interaction, context)

src/ast/nodes/NewExpression.ts

@@ -1,5 +1,4 @@
 import type MagicString from 'magic-string';
-import type { NormalizedTreeshakingOptions } from '../../rollup/types';
 import { renderCallArguments } from '../../utils/renderCallArguments';
 import type { RenderOptions } from '../../utils/renderHelpers';
 import type { HasEffectsContext, InclusionContext } from '../ExecutionContext';
@@ -21,10 +20,7 @@ export default class NewExpression extends NodeBase {
 			for (const argument of this.arguments) {
 				if (argument.hasEffects(context)) return true;
 			}
-			if (
-				(this.context.options.treeshake as NormalizedTreeshakingOptions).annotations &&
-				this.annotations
-			) {
+			if (this.annotationPure) {
 				return false;
 			}
 			return (

src/ast/nodes/shared/FunctionNode.ts

@@ -45,6 +45,11 @@ export default class FunctionNode extends FunctionBase {
 
 	hasEffects(context: HasEffectsContext): boolean {
 		if (!this.deoptimized) this.applyDeoptimizations();
+
+		if (this.annotationNoSideEffects) {
+			return false;
+		}
+
 		return !!this.id?.hasEffects(context);
 	}
 
@@ -54,6 +59,11 @@ export default class FunctionNode extends FunctionBase {
 		context: HasEffectsContext
 	): boolean {
 		if (super.hasEffectsOnInteractionAtPath(path, interaction, context)) return true;
+
+		if (this.annotationNoSideEffects) {
+			return false;
+		}
+
 		if (interaction.type === INTERACTION_CALLED) {
 			const thisInit = context.replacedVariableInits.get(this.scope.thisVariable);
 			context.replacedVariableInits.set(

src/ast/nodes/shared/Node.ts

@@ -2,7 +2,9 @@ import type * as acorn from 'acorn';
 import { locate, type Location } from 'locate-character';
 import type MagicString from 'magic-string';
 import type { AstContext } from '../../../Module';
-import { ANNOTATION_KEY, INVALID_COMMENT_KEY } from '../../../utils/pureComments';
+import type { NormalizedTreeshakingOptions } from '../../../rollup/types';
+import type { RollupAnnotation } from '../../../utils/commentAnnotations';
+import { ANNOTATION_KEY, INVALID_COMMENT_KEY } from '../../../utils/commentAnnotations';
 import type { NodeRenderOptions, RenderOptions } from '../../../utils/renderHelpers';
 import type { DeoptimizableEntity } from '../../DeoptimizableEntity';
 import type { Entity } from '../../Entity';
@@ -124,7 +126,12 @@ export interface ChainElement extends ExpressionNode {
 }
 
 export class NodeBase extends ExpressionEntity implements ExpressionNode {
-	declare annotations?: acorn.Comment[];
+	/** Marked with #__NO_SIDE_EFFECTS__ annotation */
+	declare annotationNoSideEffects?: boolean;
+	/** Marked with #__PURE__ annotation */
+	declare annotationPure?: boolean;
+	declare annotations?: RollupAnnotation[];
+
 	context: AstContext;
 	declare end: number;
 	esTreeNode: acorn.Node | null;
@@ -262,7 +269,14 @@ export class NodeBase extends ExpressionEntity implements ExpressionNode {
 			if (this.hasOwnProperty(key)) continue;
 			if (key.charCodeAt(0) === 95 /* _ */) {
 				if (key === ANNOTATION_KEY) {
-					this.annotations = value;
+					const annotations = value as RollupAnnotation[];
+					this.annotations = annotations;
+					if ((this.context.options.treeshake as NormalizedTreeshakingOptions).annotations) {
+						this.annotationNoSideEffects = annotations.some(
+							comment => comment.annotationType === 'noSideEffects'
+						);
+						this.annotationPure = annotations.some(comment => comment.annotationType === 'pure');
+					}
 				} else if (key === INVALID_COMMENT_KEY) {
 					for (const { start, end } of value as acorn.Comment[])
 						this.context.magicString.remove(start, end);

src/utils/pureComments.ts renamed to src/utils/commentAnnotations.ts

@@ -1,20 +1,32 @@
 import type * as acorn from 'acorn';
 import { base as basicWalker } from 'acorn-walk';
 import {
+	ArrowFunctionExpression,
 	BinaryExpression,
 	CallExpression,
 	ChainExpression,
 	ConditionalExpression,
+	ExportDefaultDeclaration,
+	ExportNamedDeclaration,
 	ExpressionStatement,
+	FunctionDeclaration,
 	LogicalExpression,
 	NewExpression,
-	SequenceExpression
+	SequenceExpression,
+	VariableDeclaration,
+	VariableDeclarator
 } from '../ast/nodes/NodeType';
 import { SOURCEMAPPING_URL_RE } from './sourceMappingURL';
 
+export type AnnotationType = 'noSideEffects' | 'pure';
+
+export interface RollupAnnotation extends acorn.Comment {
+	annotationType: AnnotationType;
+}
+
 interface CommentState {
 	annotationIndex: number;
-	annotations: acorn.Comment[];
+	annotations: RollupAnnotation[];
 	code: string;
 }
 
@@ -93,6 +105,28 @@ function markPureNode(node: NodeWithComments, comment: acorn.Comment, code: stri
 					invalidAnnotation = true;
 					break;
 				}
+				case ExportNamedDeclaration:
+				case ExportDefaultDeclaration: {
+					node = (node as any).declaration;
+					continue;
+				}
+				case VariableDeclaration: {
+					// case: /*#__PURE__*/ const foo = () => {}
+					const declaration = node as any;
+					if (declaration.kind === 'const') {
+						// jsdoc only applies to the first declaration
+						node = declaration.declarations[0].init;
+						continue;
+					}
+					invalidAnnotation = true;
+					break;
+				}
+				case VariableDeclarator: {
+					node = (node as any).init;
+					continue;
+				}
+				case FunctionDeclaration:
+				case ArrowFunctionExpression:
 				case CallExpression:
 				case NewExpression: {
 					break;
@@ -134,25 +168,32 @@ function doesNotMatchOutsideComment(code: string, forbiddenChars: RegExp): boole
 	return true;
 }
 
-const pureCommentRegex = /[#@]__PURE__/;
+const annotationsRegexes: [AnnotationType, RegExp][] = [
+	['pure', /[#@]__PURE__/],
+	['noSideEffects', /[#@]__NO_SIDE_EFFECTS__/]
+];
 
 export function addAnnotations(
 	comments: readonly acorn.Comment[],
 	esTreeAst: acorn.Node,
 	code: string
 ): void {
-	const annotations: acorn.Comment[] = [];
+	const annotations: RollupAnnotation[] = [];
 	const sourceMappingComments: acorn.Comment[] = [];
 	for (const comment of comments) {
-		if (pureCommentRegex.test(comment.value)) {
-			annotations.push(comment);
-		} else if (SOURCEMAPPING_URL_RE.test(comment.value)) {
+		for (const [annotationType, regex] of annotationsRegexes) {
+			if (regex.test(comment.value)) {
+				annotations.push({ ...comment, annotationType });
+			}
+		}
+		if (SOURCEMAPPING_URL_RE.test(comment.value)) {
 			sourceMappingComments.push(comment);
 		}
 	}
 	for (const comment of sourceMappingComments) {
 		annotateNode(esTreeAst, comment, false);
 	}
+
 	handlePureAnnotationsOfNode(esTreeAst, {
 		annotationIndex: 0,
 		annotations,

test/form/samples/no-side-effects-function-declaration-preserve/_config.js

@@ -0,0 +1,5 @@
+// tests compiled from https://github.com/mishoo/UglifyJS2/blob/88c8f4e363e0d585b33ea29df560243d3dc74ce1/test/compress/pure_funcs.js
+
+module.exports = defineTest({
+	description: 'preserve __NO_SIDE_EFFECTS__ annotations for function declarations'
+});

test/form/samples/no-side-effects-function-declaration-preserve/_expected.js

@@ -0,0 +1,77 @@
+/*#__NO_SIDE_EFFECTS__*/
+function fnFromSub (args) {
+  console.log(args);
+  return args
+}
+
+function fnPure(args) {
+  return args
+}
+
+function fnEffects(args) {
+  console.log(args);
+  return args
+}
+
+/*#__NO_SIDE_EFFECTS__*/
+function fnA (args) {
+  console.log(args);
+  return args
+}
+
+/*#__NO_SIDE_EFFECTS__*/
+function fnB (args) {
+  console.log(args);
+  return args
+}
+
+const fnC = /*#__NO_SIDE_EFFECTS__*/ (args) => {
+  console.log(args);
+  return args
+};
+
+
+/*#__NO_SIDE_EFFECTS__*/ 
+const fnD = (args) => {
+  console.log(args);
+  return args
+};
+
+/*#__NO_SIDE_EFFECTS__*/ 
+const fnE = (args) => {
+  console.log(args);
+  return args
+};
+
+/**
+ * This is a jsdoc comment, with no side effects annotation
+ * 
+ * @param {any} args
+ * @__NO_SIDE_EFFECTS__
+ */ 
+const fnF = (args) => {
+  console.log(args);
+  return args
+};
+
+const fnAlias = fnA;
+
+/**
+ * Have both annotations
+ * 
+ * @__PURE__
+ * @__NO_SIDE_EFFECTS__
+ */
+const fnBothAnnotations = (args) => {
+  console.log(args);
+  return args
+};
+
+// This annonation get ignored
+
+let fnLet = (args) => {
+  console.log(args);
+  return args
+};
+
+export { fnA, fnAlias, fnB, fnBothAnnotations, fnC, fnD, fnE, fnEffects, fnF, fnFromSub, fnLet, fnPure };