@atlaskit/eslint-plugin-platform 2.5.0 → 2.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@atlaskit/eslint-plugin-platform",
 	"description": "The essential plugin for use with Atlassian frontend platform tools",
-	"version": "2.5.0",
+	"version": "2.7.0",
 	"author": "Atlassian Pty Ltd",
 	"atlassian": {
 		"team": "Build Infra",
@@ -45,6 +45,15 @@
 		"@atlassian/ts-loader": "^0.1.0",
 		"@types/eslint": "^8.56.6",
 		"eslint": "^8.57.0",
+		"find-up": "^4 || ^5",
 		"outdent": "^0.5.0"
+	},
+	"peerDependencies": {
+		"find-up": "^4 || ^5"
+	},
+	"peerDependenciesMeta": {
+		"find-up": {
+			"optional": true
+		}
 	}
 }

package/src/index.tsx

@@ -28,6 +28,31 @@ import useEntrypointsInExamples from './rules/use-entrypoints-in-examples';
 import useRecommendedUtils from './rules/feature-gating/use-recommended-utils';
 import expandBackgroundShorthand from './rules/compiled/expand-background-shorthand';
 import expandSpacingShorthand from './rules/compiled/expand-spacing-shorthand';
+import noSparseCheckout from './rules/no-sparse-checkout';
+import noDirectDocumentUsage from './rules/no-direct-document-usage';
+import noSetImmediate from './rules/no-set-immediate';
+import { join, normalize } from 'node:path';
+import { readFileSync } from 'node:fs';
+
+let jiraRoot: string | undefined;
+
+try {
+	const findUp = require('find-up') as typeof import('find-up');
+	findUp.sync((dir) => {
+		const productsJsonPath = join(dir, 'products.json');
+		if (findUp.sync.exists(productsJsonPath)) {
+			const productJson: Record<string, { path: string }> = JSON.parse(
+				readFileSync(productsJsonPath, 'utf-8'),
+			);
+			if (productJson.Jira) {
+				jiraRoot = normalize(join(dir, productJson.Jira.path));
+				return findUp.stop;
+			}
+		}
+	});
+} catch {
+	// we aren't running inside of AFM, so we can ignore this.
+}
 
 const packageJson: {
 	name: string;
@@ -63,6 +88,9 @@ const rules = {
 	'no-alias': noAlias,
 	'use-entrypoints-in-examples': useEntrypointsInExamples,
 	'use-recommended-utils': useRecommendedUtils,
+	'no-sparse-checkout': noSparseCheckout,
+	'no-direct-document-usage': noDirectDocumentUsage,
+	'no-set-immediate': noSetImmediate,
 };
 
 const commonConfig = {
@@ -72,6 +100,8 @@ const commonConfig = {
 	'@atlaskit/platform/no-invalid-storybook-decorator-usage': 'error',
 	'@atlaskit/platform/ensure-atlassian-team': 'error',
 	'@atlaskit/platform/no-module-level-eval-nav4': 'error',
+	'@atlaskit/platform/no-direct-document-usage': 'warn',
+	'@atlaskit/platform/no-set-immediate': 'error',
 	// Compiled: rules that are not included via `@compiled/recommended
 	'@atlaskit/platform/expand-border-shorthand': 'error',
 	'@atlaskit/platform/expand-background-shorthand': 'error',
@@ -112,6 +142,8 @@ const jsonPrefix =
 const jsonPrefixForFlatConfig =
 	'/* eslint-disable quote-props, comma-dangle, quotes, semi, eol-last, no-template-curly-in-string */ module.exports = ';
 
+const jsonPrefixForJira = 'module.exports = ';
+
 const { name, version } = packageJson;
 const plugin = {
 	meta: {
@@ -151,7 +183,14 @@ const plugin = {
 	},
 	processors: {
 		'package-json-processor': {
-			preprocess: (source: string) => {
+			preprocess: (source, filename) => {
+				// we only need to check for jiraRoot because it uses a different
+				// ESLint version and produces fake errors due to how this processor handles JSON
+				if (jiraRoot && filename.startsWith(jiraRoot)) {
+					// augment the json into a js file
+					return [jsonPrefixForJira + source.trim()];
+				}
+
 				// augment the json into a js file
 				return [jsonPrefix + source.trim()];
 			},
@@ -177,7 +216,13 @@ const plugin = {
 		// This processor is used for ESLint FlatConfig,
 		// once we roll out FlatConfig, we can remove the above processor
 		'package-json-processor-for-flat-config': {
-			preprocess: (source: string) => {
+			// we only need to check for jiraRoot because it uses a different
+			// ESLint version and produces fake errors due to how this processor handles JSON
+			preprocess: (source, filename) => {
+				if (jiraRoot && filename.startsWith(jiraRoot)) {
+					// augment the json into a js file
+					return [jsonPrefixForJira + source.trim()];
+				}
 				// augment the json into a js file
 				return [jsonPrefixForFlatConfig + source.trim()];
 			},

package/src/rules/ensure-native-and-af-exports-synced/index.tsx

@@ -8,6 +8,9 @@ interface ExportsValidationExceptions {
 }
 
 const exportsValidationExceptions: ExportsValidationExceptions = {
+	'@af/yarn-workspace': {
+		ignoredAfExportKeys: ['./lock-parser'],
+	},
 	'@atlaskit/tokens': {
 		ignoredAfExportKeys: ['./babel-plugin'],
 	},

package/src/rules/ensure-valid-bin-values/__tests__/unit/rule.test.ts

@@ -16,8 +16,9 @@ jest.mock('fs', () => {
 	const actual = jest.requireActual('fs');
 	return {
 		...actual,
-		statSync: jest.fn((stat: string) => ({
-			isFile: jest.fn(() => mockValidBinPaths.includes(stat)),
+		statSync: jest.fn((p: string) => ({
+			isFile: jest.fn(() => mockValidBinPaths.includes(p)),
+			isDirectory: jest.fn(() => actual.statSync(p).isDirectory()),
 		})),
 	};
 });

package/src/rules/ensure-valid-platform-yarn-protocol-usage/index.ts

@@ -39,7 +39,7 @@ const rule: Rule.RuleModule = {
 		},
 		hasSuggestions: false,
 		messages: {
-			invalidWorkspaceProtocolUsage: `The 'workspace:^' or 'workspace:~' protocol is Used. To resolve this error, please use the 'workspace:*' protocol instead.`,
+			invalidWorkspaceProtocolUsage: `The 'workspace:^'protocol is Used. To resolve this error, please use the 'workspace:*' protocol instead.`,
 			invalidRootProtocolUsage: `The 'root:' protocol is not allowed in platform packages. To resolve this error, replace the 'root:' protocol with specific package versions (e.g. '^1.0.0').`,
 		},
 	},

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

@@ -68,7 +68,7 @@ const rule: Rule.RuleModule = {
 		},
 		messages: {
 			useConfig:
-				'Do not precondition gates or experiments with another gate. Configure this in Statsig instead to reduce unnecessary code and simplify cleanup.',
+				'Do not precondition gates or experiments with another gate. Configure this in Statsig instead to reduce unnecessary code, simplify cleanup and to ensure accurate exposures in Statsig.',
 			incorrectExposure:
 				'Evaluate gates or experiments at the end of your logical expression to ensure exposure is tracked correctly.',
 		},

package/src/rules/no-direct-document-usage/index.tsx

@@ -0,0 +1,111 @@
+import type { Rule } from 'eslint';
+import { skipForExampleFiles, skipForTestFiles } from '../util/file-exclusions';
+
+const rule: Rule.RuleModule = {
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Enforce using getDocument from @atlaskit/browser-apis instead of direct document usage',
+			recommended: true,
+		},
+		messages: {
+			useGetDocument:
+				'Use getDocument from @atlaskit/browser-apis instead of direct document usage',
+		},
+		schema: [],
+	},
+	create(context) {
+		let hasGetDocumentImport = false;
+		const filename = context.filename;
+
+		// Skip test files
+		const skipResult = skipForTestFiles(context);
+		if (skipResult) {
+			return skipResult;
+		}
+
+		// Skip example files
+		const skipResult2 = skipForExampleFiles(context);
+		if (skipResult2) {
+			return skipResult2;
+		}
+
+		// Skip the getDocument.ts file itself
+		if (filename.endsWith('getDocument.ts')) {
+			return {};
+		}
+
+		return {
+			ImportDeclaration(node) {
+				if (
+					node.source.value === '@atlaskit/browser-apis' &&
+					node.specifiers.some(
+						(specifier) =>
+							specifier.type === 'ImportSpecifier' &&
+							specifier.imported.type === 'Identifier' &&
+							specifier.imported.name === 'getDocument',
+					)
+				) {
+					hasGetDocumentImport = true;
+				}
+			},
+			Identifier(node) {
+				if (node.name === 'document' && !hasGetDocumentImport) {
+					const parent = node.parent;
+
+					// Skip if 'document' is used as a property key in an object literal
+					if (parent?.type === 'Property' && parent.key === node) {
+						return;
+					}
+
+					// Skip if 'document' is used as a shorthand property value
+					if (parent?.type === 'Property' && parent.value === node && parent.shorthand) {
+						return;
+					}
+
+					// Skip if 'document' is used as a property being accessed in a member expression
+					if (parent?.type === 'MemberExpression' && parent.property === node && !parent.computed) {
+						return;
+					}
+
+					// Skip if 'document' is being declared as a variable
+					if (parent?.type === 'VariableDeclarator' && parent.id === node) {
+						return;
+					}
+
+					// Skip if 'document' is a function name
+					if (parent?.type === 'FunctionDeclaration' && 'id' in parent && parent.id === node) {
+						return;
+					}
+
+					if (parent?.type === 'FunctionExpression' && 'id' in parent && parent.id === node) {
+						return;
+					}
+
+					// Skip if 'document' is a method name in a class or object
+					if (parent?.type === 'MethodDefinition' && parent.key === node) {
+						return;
+					}
+
+					// Skip if 'document' is being assigned to (shadowing the global)
+					if (parent?.type === 'AssignmentExpression' && parent.left === node) {
+						return;
+					}
+
+					// Skip if 'document' is in a destructuring pattern (could be destructuring from an object)
+					if (parent?.type === 'ObjectPattern' || parent?.type === 'ArrayPattern') {
+						return;
+					}
+
+					context.report({
+						node,
+						messageId: 'useGetDocument',
+					});
+				}
+			},
+		};
+	},
+};
+
+export default rule;

package/src/rules/no-set-immediate/index.tsx

@@ -0,0 +1,43 @@
+import type { Rule } from 'eslint';
+
+const rule: Rule.RuleModule = {
+	meta: {
+		docs: {
+			description:
+				"Prevent usage of setImmediate in favor of React Testing Library's `waitFor` or similar",
+			recommended: true,
+		},
+		type: 'problem',
+		messages: {
+			noSetImmediate:
+				"Avoid using setImmediate. Use React Testing Library's waitFor or similar instead for better test reliability.",
+			suggestWaitFor: 'Replace with waitFor from @testing-library/react or similar',
+		},
+		hasSuggestions: true,
+	},
+	create(context) {
+		return {
+			CallExpression(node) {
+				if (node.callee.type === 'Identifier' && node.callee.name === 'setImmediate') {
+					context.report({
+						node,
+						messageId: 'noSetImmediate',
+						suggest: [
+							{
+								messageId: 'suggestWaitFor',
+								fix(fixer) {
+									return fixer.replaceText(
+										node,
+										'await waitFor(() => { /* your assertion here */ })',
+									);
+								},
+							},
+						],
+					});
+				}
+			},
+		};
+	},
+};
+
+export default rule;

package/src/rules/no-sparse-checkout/__tests__/unit/rule.test.tsx

@@ -0,0 +1,48 @@
+import { tester } from '../../../../__tests__/utils/_tester';
+import rule from '../../index';
+
+describe('test no-sparse-checkout rule', () => {
+	tester.run('no-sparse-checkout', rule, {
+		valid: [
+			{
+				code: `
+					const config = {
+						clone: alias.afmClone({ sparseCheckout: false })
+					};
+				`,
+				filename: 'hello/foo.ts',
+			},
+			{
+				code: `
+					const config = {
+						clone: alias.afmClone({ cloneDepth: 1})
+					};
+				`,
+				filename: 'hello/foo.ts',
+			},
+		],
+		invalid: [
+			{
+				code: `
+					const config = {
+						clone: alias.afmClone({ sparseCheckout: true })
+					};
+				`,
+				filename: 'hello/foo.ts',
+				errors: [{ messageId: 'noSparseCheckout' }],
+			},
+			{
+				code: `
+					const config = {
+						clone: alias.afmClone({ 
+							cloneDepth: 'full',
+							sparseCheckout: true 
+						})
+					};
+				`,
+				filename: 'hello/foo.ts',
+				errors: [{ messageId: 'noSparseCheckout' }],
+			},
+		],
+	});
+});

package/src/rules/no-sparse-checkout/index.tsx

@@ -0,0 +1,54 @@
+import type { Rule } from 'eslint';
+import type { Property } from 'estree';
+
+// We will be removing sparse checkout from pipelines in CI completely due to the load it causes on BBC.
+// We will be incrementally removing sparse-checkout from the files below as it is probably unnecessasry.
+// If you must add an exception below, please go through the chopper process before doing so
+const sparseCheckoutExceptions = [
+	'bitbucket-pipelines/pipelines/custom/run-issue-automat.ts',
+	'bitbucket-pipelines/pipelines/custom/marketplace/utils.ts',
+	'bitbucket-pipelines/pipelines/custom/confluence/utils/index.ts',
+	'bitbucket-pipelines/pipelines/custom/afm-tools/upload-afm-dependency-graph-cache.ts',
+	'bitbucket-pipelines/pipelines/custom/afm-tools/default-afm-tools.ts',
+	'bitbucket-pipelines/pipelines/custom/marketplace/utils.ts',
+	'bitbucket-pipelines/pipelines/custom/afm-git-hooks.ts',
+	'bitbucket-pipelines/pipelines/custom/update-codeowners-and-teams-gen.ts',
+	'bitbucket-pipelines/pipelines/custom/run-issue-automat.ts',
+];
+
+const rule: Rule.RuleModule = {
+	meta: {
+		docs: {
+			recommended: false,
+		},
+		type: 'problem',
+		messages: {
+			noSparseCheckout:
+				'Sparse checkout is not allowed in pipeline configurations. Use git-alternates instead by setting sparseCheckout to false or add this file to exceptions.',
+		},
+	},
+
+	create(context) {
+		const fileName = context.filename;
+		if (sparseCheckoutExceptions.some((exception) => fileName.endsWith(exception))) {
+			return {};
+		}
+
+		return {
+			// Look for calls to afmClone or objects that match AFMCloneConfig type
+			'CallExpression[callee.object.name=alias][callee.property.name=afmClone] ObjectExpression Property':
+				(node: Property) => {
+					if (node.key.type === 'Identifier' && node.key.name === 'sparseCheckout') {
+						if (node.value.type === 'Literal' && node.value.value === true) {
+							context.report({
+								node,
+								messageId: 'noSparseCheckout',
+							});
+						}
+					}
+				},
+		};
+	},
+};
+
+export default rule;

package/src/rules/util/file-exclusions.ts

@@ -0,0 +1,39 @@
+import type { Rule } from 'eslint';
+
+/**
+ * Common patterns for test files that should be excluded from rules
+ */
+const TEST_FILE_PATTERNS = ['__tests__', 'test', 'spec'] as const;
+
+/**
+ * Checks if a file should be excluded from rules based on test file patterns
+ * @param filename The filename to check
+ * @returns true if the file should be excluded, false otherwise
+ */
+const isTestFile = (filename: string): boolean => {
+	return TEST_FILE_PATTERNS.some((pattern) => filename.includes(pattern));
+};
+
+/**
+ * Helper function to skip rules for test files
+ * @param context The ESLint rule context
+ * @returns An empty RuleListener if the file is a test file, undefined otherwise
+ */
+export const skipForTestFiles = (context: Rule.RuleContext): Rule.RuleListener | undefined => {
+	if (isTestFile(context.filename)) {
+		return {};
+	}
+	return undefined;
+};
+
+/**
+ * Helper function to skip rules for example files
+ * @param context The ESLint rule context
+ * @returns An empty RuleListener if the file is an example file, undefined otherwise
+ */
+export const skipForExampleFiles = (context: Rule.RuleContext): Rule.RuleListener | undefined => {
+	if (context.filename.includes('example')) {
+		return {};
+	}
+	return undefined;
+};