@atlaskit/eslint-plugin-platform 0.6.1 → 0.7.0

package/src/rules/no-pre-post-installs/index.ts

@@ -2,34 +2,34 @@
 import type { Rule } from 'eslint';
 
 const rule: Rule.RuleModule = {
-  meta: {
-    type: 'problem',
-    docs: {
-      description:
-        'This rule disallows public packages to have pre/post install scripts as installations can happen on different environments',
-      recommended: false,
-    },
-    hasSuggestions: false,
-    messages: {
-      prePostInstallScriptsNotAllowed:
-        'pre/post install scripts not allowed in package.json',
-    },
-  },
-  create(context) {
-    return {
-      'ObjectExpression Property[key.value=scripts] Property[key.value=/^(pre|post)install$/]':
-        (node: Rule.Node) => {
-          if (!context.getFilename().endsWith('/package.json')) {
-            return;
-          }
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'This rule disallows public packages to have pre/post install scripts as installations can happen on different environments',
+			recommended: false,
+		},
+		hasSuggestions: false,
+		messages: {
+			prePostInstallScriptsNotAllowed: 'pre/post install scripts not allowed in package.json',
+		},
+	},
+	create(context) {
+		return {
+			'ObjectExpression Property[key.value=scripts] Property[key.value=/^(pre|post)install$/]': (
+				node: Rule.Node,
+			) => {
+				if (!context.getFilename().endsWith('/package.json')) {
+					return;
+				}
 
-          return context.report({
-            node,
-            messageId: 'prePostInstallScriptsNotAllowed',
-          });
-        },
-    };
-  },
+				return context.report({
+					node,
+					messageId: 'prePostInstallScriptsNotAllowed',
+				});
+			},
+		};
+	},
 };
 
 export default rule;

package/src/rules/no-preconditioning/README.md

@@ -0,0 +1,69 @@
+# Enforce feature gate not used as a precondition in logical expressions (feature-flags/no-preconditioning)
+
+Using a feature gate as a precondition in logical expressions can cause:
+
+- Exposure to be tracked incorrectly
+- Unnecessary code
+
+## Examples
+
+Instead of adding prerequisite gating in code, configure this in Statsig UI by adding rules to gates
+and targeting for experiments. This will reduce unnecessary complexity in code and simplify cleanup.
+
+```tsx
+import { fg } from '@atlassian/jira-feature-gating';
+import { expVal } from '@atlassian/jira-feature-experiments';
+
+// Setup rule in `feature_milestone2` to fail if `feature_milestone1` fails
+if (fg('feature_milestone1') && fg('feature_milestone2')) {
+	doSomething();
+}
+
+// Setup targeting in `my_exp` to only enroll participants passing `my_gate`
+if (fg('my_gate') && expVal('my_exp')) {
+	doSomething();
+}
+```
+
+Gating experiment values from same or different experiments is valid.
+
+```tsx
+import { expVal } from '@atlassian/jira-feature-experiments';
+
+if (expVal('my_exp', 'delayRetries', false) && expVal('my_exp', 'numRetries', 0) > 3) {
+	doSomething();
+}
+```
+
+👎 Examples of **incorrect** exposure tracking
+
+If `isAdmin` is false exposure will be fired even though feature was not intended for audience.
+
+```tsx
+import { fg } from '@atlassian/jira-feature-gating';
+
+if (fg('my_gate') && isAdmin) {
+	doSomething();
+}
+```
+
+If `hasSelectedProject` is false and experiment returns true. Expsoure will be tracked as true even
+though feature was not exposed to the user.
+
+```tsx
+import { fg } from '@atlassian/jira-feature-gating';
+
+if (expVal('my_experiment', 'is_enabled', false) && hasSelectedProject) {
+	doSomething();
+}
+```
+
+👍 Examples of **correct** exposure tracking
+
+```tsx
+import { fg } from '@atlassian/jira-feature-gating';
+
+if (isAdmin && fg('my_gate')) {
+	doSomething();
+}
+```

package/src/rules/no-preconditioning/__tests__/rule.test.tsx

@@ -0,0 +1,164 @@
+import outdent from 'outdent';
+import { tester } from '../../../__tests__/utils/_tester';
+import rule from '../index';
+
+tester.run('feature-flags/no-preconditioning', rule, {
+	valid: [
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+
+                if (preCheck && fg('gate')) {}
+            `,
+		},
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+
+                if (preCheck1 && preCheck2 && fg('gate')) {}
+            `,
+		},
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+
+                const value = fg('gate') && 'value';
+            `,
+		},
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+
+                const value = preCheck && fg('gate') ? 'value' : '';
+            `,
+		},
+		{
+			code: outdent`
+                import { expVal } from '@atlassian/jira-feature-experiments';
+
+                if (expVal('one') && expVal('two') ) {}
+            `,
+		},
+		{
+			code: outdent`
+                import { expVal, expValEquals } from '@atlassian/jira-feature-experiments';
+
+                if (expVal('one') && expValEquals('two', 'value') ) {}
+            `,
+		},
+		{
+			code: outdent`
+                import { expVal } from '@atlassian/jira-feature-experiments';
+
+                if (expVal('one') || expVal('two') ) {}
+            `,
+		},
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+
+                if (preGate && fg('one') || preGate && fg('two') ) {}
+            `,
+		},
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+
+                if (count > 0 && fg('my_gate') ) {}
+            `,
+		},
+	],
+	invalid: [
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+
+                if (fg('one') && fg('two')) {}
+            `,
+			errors: [{ messageId: 'useConfig' }],
+		},
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+                import { expVal } from '@atlassian/jira-feature-experiments';
+
+                if (expVal('one') && fg('two')) {}
+            `,
+			errors: [{ messageId: 'useConfig' }],
+		},
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+                import { expVal } from '@atlassian/jira-feature-experiments';
+
+                if (fg('one') && fg('two') && expVal('three')) {}
+            `,
+			errors: [{ messageId: 'useConfig' }],
+		},
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+
+                if (preCheck && fg('one') && fg('two')) {}
+            `,
+			errors: [{ messageId: 'useConfig' }],
+		},
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+                import { expVal } from '@atlassian/jira-feature-experiments';
+
+                if (fg('my_gate') && expVal('my_exp', 'cohort', 'not-enrolled') === 'variation') {}
+            `,
+			errors: [{ messageId: 'useConfig' }],
+		},
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+
+                const value = fg('one') && preCheck && fg('two') ? 'value' : '';
+            `,
+			errors: [{ messageId: 'incorrectExposure' }],
+		},
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+
+                if (fg('gate') && isAdmin) {}
+            `,
+			errors: [{ messageId: 'incorrectExposure' }],
+		},
+		{
+			code: outdent`
+                import { expVal } from '@atlassian/jira-feature-experiments';
+
+                if (expVal('exp') && isAdmin) {}
+            `,
+			errors: [{ messageId: 'incorrectExposure' }],
+		},
+		{
+			code: outdent`
+                import { expValEquals } from '@atlassian/jira-feature-experiments';
+
+                if (expValEquals('exp', 'value') && isAdmin) {}
+            `,
+			errors: [{ messageId: 'incorrectExposure' }],
+		},
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+
+                if (fg('one') && fg('two') && isAdmin) {}
+            `,
+			errors: [{ messageId: 'incorrectExposure' }, { messageId: 'useConfig' }],
+		},
+		{
+			code: outdent`
+                import { fg } from '@atlassian/jira-feature-gating';
+
+                if (preGate && fg('one') || fg('two') && preGate ) {}
+            `,
+			errors: [{ messageId: 'incorrectExposure' }],
+		},
+	],
+});

package/src/rules/no-preconditioning/index.tsx

@@ -0,0 +1,138 @@
+import type { Rule } from 'eslint';
+import { isAPIimport, type Node } from '../utils';
+
+const isAndExpression = (node: Rule.Node): node is Node<'LogicalExpression'> =>
+	node.type === 'LogicalExpression' && node.operator === '&&';
+
+const isExpUsage = (calleeName: string) => calleeName === 'expVal' || calleeName === 'expValEquals';
+
+const getGateType = (node: Rule.Node, context: Rule.RuleContext): string => {
+	const { type } = node;
+
+	if (type === 'BinaryExpression') {
+		return (
+			getGateType(node.left as Node<'BinaryExpression'>, context) ||
+			getGateType(node.right as Node<'BinaryExpression'>, context)
+		);
+	}
+
+	if (node.type === 'CallExpression') {
+		const { callee } = node;
+
+		const isFeatureGate =
+			type === 'CallExpression' &&
+			callee.type === 'Identifier' &&
+			// Experiments cannot have other experiments as preconditions, only gates
+			(callee.name === 'fg' || isExpUsage(callee.name)) &&
+			isAPIimport(callee.name, context);
+
+		return isFeatureGate ? callee.name : '';
+	}
+
+	return '';
+};
+
+const getPreconditionStatus = (
+	logicalExpression: Node<'LogicalExpression'>,
+	context: Rule.RuleContext,
+) => {
+	const { left } = logicalExpression as any;
+	// If left side is a nested AND expression then the left side node is on the nested's right
+	const leftGateType = getGateType(isAndExpression(left) ? left.right : left, context);
+
+	if (leftGateType) {
+		const rightGateType = getGateType(logicalExpression.right as any, context);
+		// Check this scenario: fg('gate') && isAdmin
+		if (!rightGateType) {
+			return 'early-exposure';
+		}
+
+		// Using experiment values in logical expressions in valid
+		// i.e. expVal() && expVal()
+		if (isExpUsage(leftGateType) && isExpUsage(rightGateType)) {
+			return '';
+		}
+
+		// Then is scenario: fg('gate1') && fg('gate2')
+		return 'unnecessary-gate';
+	}
+
+	return '';
+};
+
+const rule: Rule.RuleModule = {
+	meta: {
+		docs: {
+			description: 'Inform on how to use gates and experiments in logical expressions',
+			url: 'https://stash.atlassian.com/projects/ATLASSIAN/repos/atlassian-frontend-monorepo/browse/platform/packages/platform/eslint-plugin/src/rules/ff/no-preconditioning/README.md',
+		},
+		messages: {
+			useConfig:
+				'Do not precondition gates or experiments with another gate. Configure this in Statsig instead to reduce unnecessary code and simplify cleanup.',
+			incorrectExposure:
+				'Evaluate gates or experiments at the end of your logical expression to ensure exposure is tracked correctly.',
+		},
+	},
+	create(context) {
+		return {
+			'LogicalExpression[operator="&&"]': (node: Node<'LogicalExpression'>) => {
+				const { parent } = node;
+				// Don't analyze nested AND logical expressions
+				if (isAndExpression(parent)) {
+					return;
+				}
+
+				const isAssignmentStatement =
+					parent.type !== 'IfStatement' &&
+					parent.type !== 'ConditionalExpression' &&
+					// @ts-expect-error — this isn't a valid statement but does fail tests when removed.
+					// When updating this rule please resolve this supression.
+					!(parent.type === 'LogicalExpression' && parent.operator === '||');
+
+				let nextLogicalExpression: Node<'LogicalExpression'> | undefined = node;
+				let exposureReported = false;
+				let configReported = false;
+
+				while (nextLogicalExpression) {
+					const preconditionStatus = getPreconditionStatus(nextLogicalExpression, context);
+					// Allow us to check for: fg('') && <Component />
+					const isReturningValue =
+						// Check if we are on the root logical expression
+						// as this is where the returning value is
+						// `node` is root logical expression
+						isAssignmentStatement && nextLogicalExpression === node;
+
+					if (!exposureReported && !isReturningValue && preconditionStatus === 'early-exposure') {
+						context.report({
+							messageId: 'incorrectExposure',
+							node,
+						});
+
+						exposureReported = true;
+					}
+
+					if (!configReported && preconditionStatus === 'unnecessary-gate') {
+						context.report({
+							messageId: 'useConfig',
+							node,
+						});
+
+						configReported = true;
+					}
+
+					if (exposureReported && configReported) {
+						return;
+					}
+
+					nextLogicalExpression = isAndExpression(
+						nextLogicalExpression.left as Node<'LogicalExpression'>,
+					)
+						? (nextLogicalExpression.left as Node<'LogicalExpression'>)
+						: undefined;
+				}
+			},
+		};
+	},
+};
+
+export default rule;

package/src/rules/prefer-fg/README.md

@@ -0,0 +1,3 @@
+# Keep usages of boolean feature flags consistent (feature-flags/prefer-fg)
+
+Use `fg` with boolean feature flags

package/src/rules/prefer-fg/__tests__/rule.test.tsx

@@ -0,0 +1,83 @@
+import outdent from 'outdent';
+import { tester } from '../../../__tests__/utils/_tester';
+import rule from '../index';
+
+const errors = [{ messageId: 'autoFixImports' }, { messageId: 'preferFG' }];
+
+tester.run('feature-flags/prefer-fg', rule, {
+	valid: [
+		{
+			code: outdent`
+                import { getFeatureFlagValue } from '@atlassian/jira-feature-flagging';
+
+                const ffVal = getFeatureFlagValue('get.value', '');
+            `,
+		},
+		{
+			code: outdent`
+                import { getFeatureFlagValue } from '@atlassian/jira-feature-flagging';
+
+                const ffVal = getFeatureFlagValue('get.value', {});
+            `,
+		},
+		{
+			code: outdent`
+                import { getFeatureFlagValue } from '@atlassian/jira-feature-flagging-using-meta';
+
+                const ffVal = getFeatureFlagValue('get.value', 0);
+            `,
+		},
+		{
+			code: outdent`
+                import { getFeatureFlagValue } from '@atlassian/jira-feature-flagging-using-meta';
+
+                const isEnabled = getFeatureFlagValue('is.enabled', true);
+            `,
+		},
+		{
+			code: outdent`
+                import { getFeatureFlagValue, getFeatureFlagClient } from '@atlassian/jira-feature-flagging-using-meta';
+
+                const ffVal = getFeatureFlagValue('get.value', {});
+                const newVal = getFeatureFlagClient().getFlagEvaluation('get.value', {});
+            `,
+		},
+		{
+			code: outdent`
+                import { getFeatureFlagValue } from 'thirdparty';
+
+                const isEnabled = getFeatureFlagValue('is.enabled', false);
+            `,
+		},
+	],
+	invalid: [
+		{
+			code: outdent`
+                import { getBooleanFF, fg } from '@atlaskit/platform-feature-flags';
+
+                const isCorrect = fg('is.correct');
+                const isAlsoEnabled = getBooleanFF('is.also.enabled', false);
+            `,
+			output: outdent`
+                import { fg } from '@atlaskit/platform-feature-flags';
+
+                const isCorrect = fg('is.correct');
+                const isAlsoEnabled = fg('is.also.enabled');
+            `,
+			errors,
+		},
+		{
+			code: outdent`
+                import { getBooleanFF } from '@atlaskit/platform-feature-flags';
+
+                const isEnabled = getBooleanFF('is.enabled', false);
+            `,
+			output: outdent`
+                import { fg } from '@atlaskit/platform-feature-flags';
+
+                const isEnabled = fg('is.enabled');
+            `,
+			errors: [{ messageId: 'autoFixImports' }, { messageId: 'preferFG' }],
+		},
+	],
+});

package/src/rules/prefer-fg/index.tsx

@@ -0,0 +1,108 @@
+import type { Rule } from 'eslint';
+
+import { FEATURE_API_IMPORT_SOURCES } from '../constants';
+import { type Node } from '../utils';
+
+const validateUsage = (
+	node: Node<'CallExpression'>,
+	utilName: string,
+	context: Rule.RuleContext,
+	changeMap: Map<any, any>,
+) => {
+	const resolved = context
+		.getScope()
+		.references.find((ref) => ref.identifier.name === utilName)?.resolved;
+
+	const importSpecifierDefinition = resolved?.defs.find(
+		(def: any) =>
+			def.node?.type === 'ImportSpecifier' &&
+			FEATURE_API_IMPORT_SOURCES.has(def.parent?.source.value),
+	);
+
+	if (importSpecifierDefinition) {
+		const [flagNameArg] = node.arguments;
+
+		context.report({
+			messageId: 'preferFG',
+			node,
+			*fix(fixer) {
+				yield fixer.replaceText(node, `fg(${context.sourceCode.getText(flagNameArg)})`);
+
+				const importDeclaration = importSpecifierDefinition.parent;
+
+				if (changeMap.has(importDeclaration)) {
+					const changeCounts = changeMap.get(importDeclaration);
+
+					changeMap.set(importDeclaration, {
+						...changeCounts,
+						[utilName]: changeCounts[utilName] + 1 || 1,
+					});
+				} else {
+					changeMap.set(importDeclaration, { [utilName]: 1 });
+				}
+			},
+		});
+	}
+};
+
+const rule: Rule.RuleModule = {
+	meta: {
+		docs: {
+			url: 'https://stash.atlassian.com/projects/ATLASSIAN/repos/atlassian-frontend-monorepo/browse/platform/packages/platform/eslint-plugin/src/rules/ff/prefer-fg/README.md',
+			description: 'Keep usages of boolean feature flags consistent',
+		},
+		fixable: 'code',
+		messages: {
+			preferFG: 'Use `fg` instead for boolean feature flags',
+			autoFixImports: 'Use `fg` instead for boolean feature flags',
+		},
+	},
+	create(context) {
+		let changeMap: Map<any, any>;
+
+		return {
+			'CallExpression[callee.name="getBooleanFF"]': (node: Node<any>) => {
+				if (node.type !== 'CallExpression') {
+					return;
+				}
+
+				changeMap = changeMap || new Map();
+				validateUsage(node, 'getBooleanFF', context, changeMap);
+			},
+			'Program:exit': () => {
+				if (changeMap?.size) {
+					changeMap.forEach((changeCounts, importDeclaration) => {
+						const [moduleScope] = context.getScope().childScopes;
+						const importSpecifiers = new Set(
+							importDeclaration.specifiers.map(({ imported }: any) => imported.name),
+						);
+
+						importSpecifiers.add('fg');
+
+						Object.keys(changeCounts).forEach((utilName) => {
+							if (changeCounts[utilName] === moduleScope.set.get(utilName)?.references.length) {
+								importSpecifiers.delete(utilName);
+							}
+						});
+
+						context.report({
+							messageId: 'autoFixImports',
+							node: importDeclaration,
+							fix: (fixer) =>
+								fixer.replaceText(
+									importDeclaration,
+									`import { ${Array.from(importSpecifiers).join(', ')} } from '${
+										importDeclaration.source.value
+									}';`,
+								),
+						});
+					});
+
+					changeMap.clear();
+				}
+			},
+		};
+	},
+};
+
+export default rule;

package/src/rules/static-feature-flags/README.md

@@ -0,0 +1,3 @@
+# Ensure `featureFlagName` is a string literal (feature-flags/static-feature-flags) 🍊
+
+Ensure feature flags are static