@atlaskit/eslint-plugin-platform 2.8.0 → 2.9.0

package/dist/cjs/rules/visit-example-type-import-required/index.js

@@ -0,0 +1,409 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.RULE_NAME = void 0;
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
+var _fs = _interopRequireDefault(require("fs"));
+var _path = _interopRequireDefault(require("path"));
+var _utils = require("@typescript-eslint/utils");
+var _typescriptEstree = require("@typescript-eslint/typescript-estree");
+function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t.return || t.return(); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+var RULE_NAME = exports.RULE_NAME = 'visit-example-type-import-required';
+var messages = {
+  missingTypeofImport: 'visitExample must use typeof import(...) generic type parameter. ' + 'Use visitExample<typeof import("path/to/example.tsx")>(groupId, packageId, exampleId).',
+  invalidTypeParameter: 'visitExample generic type parameter must be a typeof import(...) expression.',
+  pathMismatch: 'The import path "{{ importPath }}" does not match the expected example file for ' + 'visitExample({{ groupId }}, {{ packageId }}, {{ exampleId }}). ' + 'Expected import to resolve to: {{ expectedPath }}',
+  noPackageImports: 'Package imports (e.g., @atlaskit/...) are not allowed in visitExample type parameters. Use a relative import path.',
+  typeAliasNotInlined: 'Type aliases for typeof import(...) must be inlined directly into the visitExample call. ' + 'Use visitExample<typeof import("...")>(...) instead of defining a type alias.',
+  suggestFixPath: 'Update import path to match visitExample arguments'
+};
+function isTargetFile(filename) {
+  return filename.endsWith('.spec.tsx');
+}
+
+/**
+ * Extracts the import path string from a TSTypeQuery node of the form `typeof import('...')`.
+ * Returns null if the node doesn't match that shape.
+ */
+function extractImportPathFromTypeQuery(typeQuery) {
+  // TSTypeQuery { exprName: TSImportType { argument: TSLiteralType { literal: Literal } } }
+  var exprName = typeQuery.exprName;
+  if (exprName.type !== _utils.AST_NODE_TYPES.TSImportType) {
+    return null;
+  }
+  var argument = exprName.argument;
+  if (argument.type === _utils.AST_NODE_TYPES.TSLiteralType && argument.literal.type === _utils.AST_NODE_TYPES.Literal && typeof argument.literal.value === 'string') {
+    return argument.literal.value;
+  }
+  return null;
+}
+/**
+ * Builds a map of all TSTypeAliasDeclaration nodes in the file, keyed by name.
+ * Each entry records whether the alias is at the top level of the program (file-level).
+ */
+function collectTypeAliases(ast) {
+  var result = new Map();
+
+  // Cast through unknown to work around a version mismatch: @typescript-eslint/utils
+  // vendors its own copy of @typescript-eslint/types (v7) while the root node_modules
+  // has a different version (v5). The TSESTree types are structurally identical at
+  // runtime — the cast is safe.
+  (0, _typescriptEstree.simpleTraverse)(ast, {
+    enter: function enter(node, parent) {
+      // A type alias is "file-level" if its immediate parent is the Program,
+      // or if it's the declaration of a top-level ExportNamedDeclaration.
+      if (node.type === _utils.AST_NODE_TYPES.TSTypeAliasDeclaration) {
+        var isFileLevel = (parent === null || parent === void 0 ? void 0 : parent.type) === _utils.AST_NODE_TYPES.Program || (parent === null || parent === void 0 ? void 0 : parent.type) === _utils.AST_NODE_TYPES.ExportNamedDeclaration;
+        result.set(node.id.name, {
+          node: node,
+          isFileLevel: isFileLevel
+        });
+      }
+    }
+  });
+  return result;
+}
+
+/**
+ * Resolves a top-level `const foo = 'literal'` declaration to its string value.
+ * Returns null for non-const, non-string, or not-found variables.
+ */
+function resolveVariableToConstant(programBody, variableName, cache) {
+  if (cache.has(variableName)) {
+    var _cache$get;
+    return (_cache$get = cache.get(variableName)) !== null && _cache$get !== void 0 ? _cache$get : null;
+  }
+  var _iterator = _createForOfIteratorHelper(programBody),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var node = _step.value;
+      if (node.type !== _utils.AST_NODE_TYPES.VariableDeclaration || node.kind !== 'const') {
+        continue;
+      }
+      var _iterator2 = _createForOfIteratorHelper(node.declarations),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var _declarator$init;
+          var declarator = _step2.value;
+          if (declarator.id.type === _utils.AST_NODE_TYPES.Identifier && declarator.id.name === variableName && ((_declarator$init = declarator.init) === null || _declarator$init === void 0 ? void 0 : _declarator$init.type) === _utils.AST_NODE_TYPES.Literal && typeof declarator.init.value === 'string') {
+            cache.set(variableName, declarator.init.value);
+            return declarator.init.value;
+          }
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  cache.set(variableName, null);
+  return null;
+}
+/**
+ * Extracts the (groupId, packageId, exampleId) string arguments from a visitExample call.
+ * Each argument may be a string literal or a reference to a top-level const string variable.
+ * Returns null for any argument that can't be statically resolved.
+ */
+function extractCallArgs(node, programBody, variableCache) {
+  if (node.arguments.length < 3) {
+    return null;
+  }
+  function resolveArg(arg) {
+    if (arg.type === _utils.AST_NODE_TYPES.Literal && typeof arg.value === 'string') {
+      return arg.value;
+    }
+    if (arg.type === _utils.AST_NODE_TYPES.Identifier) {
+      return resolveVariableToConstant(programBody, arg.name, variableCache);
+    }
+    return null;
+  }
+  var groupId = resolveArg(node.arguments[0]);
+  var packageId = resolveArg(node.arguments[1]);
+  var exampleId = resolveArg(node.arguments[2]);
+  if (!groupId || !packageId || !exampleId) {
+    return null;
+  }
+  return {
+    groupId: groupId,
+    packageId: packageId,
+    exampleId: exampleId
+  };
+}
+function getPackagesBasePath(testFilePath) {
+  var testFileDir = _path.default.dirname(testFilePath);
+  var testFileSegments = testFileDir.split(_path.default.sep);
+  var packagesIndex = testFileSegments.findIndex(function (seg) {
+    return seg === 'packages';
+  });
+  if (packagesIndex === -1) {
+    return null;
+  }
+  var baseSegments = testFileSegments.slice(0, packagesIndex + 1);
+  var basePath = _path.default.isAbsolute(testFilePath) ? _path.default.resolve.apply(_path.default, ['/'].concat((0, _toConsumableArray2.default)(baseSegments))) : _path.default.resolve.apply(_path.default, [process.cwd()].concat((0, _toConsumableArray2.default)(baseSegments)));
+  return {
+    basePath: basePath,
+    packagesIndex: packagesIndex
+  };
+}
+
+/**
+ * Resolves the expected example file path from visitExample arguments.
+ *
+ * visitExample('groupId', 'packageId', 'exampleId') maps to:
+ *   packages/{groupId}/{packageId}/examples/{exampleId}.tsx
+ *
+ * Example files may also have a numeric sort prefix, e.g.:
+ *   packages/{groupId}/{packageId}/examples/00-{exampleId}.tsx
+ *
+ * We scan the examples directory once and match against all candidates.
+ * Falls back to the bare `{exampleId}.tsx` name when the directory can't
+ * be read (e.g. in unit-test environments where the files don't exist).
+ */
+function resolveExamplePathFromArgs(groupId, packageId, exampleId, testFilePath) {
+  var packagesBase = getPackagesBasePath(testFilePath);
+  if (!packagesBase) {
+    return null;
+  }
+  var examplesDir = _path.default.resolve(packagesBase.basePath, groupId, packageId, 'examples');
+  var fallback = _path.default.resolve(examplesDir, "".concat(exampleId, ".tsx"));
+
+  // Match: exact name OR numeric-prefixed variant, with optional `.examples` infix
+  var candidateRe = new RegExp("^(?:\\d+-)?".concat(exampleId, "(?:\\.examples?)?\\.tsx$"));
+  try {
+    var match = _fs.default.readdirSync(examplesDir).find(function (f) {
+      return candidateRe.test(f);
+    });
+    if (match) {
+      return _path.default.resolve(examplesDir, match);
+    }
+  } catch (_unused) {
+    // Directory doesn't exist or can't be read (e.g. in test environments)
+  }
+  return fallback;
+}
+
+/**
+ * Computes a relative import path from one file to another
+ */
+function computeRelativeImportPath(fromFile, toFile) {
+  var fromDir = _path.default.dirname(fromFile);
+  var relativePath = _path.default.relative(fromDir, toFile);
+  // Normalize to forward slashes for import statements (standard in JavaScript/TypeScript)
+  relativePath = relativePath.replace(/\\/g, '/');
+  // Ensure relative imports start with ./ or ../
+  if (!relativePath.startsWith('.') && !relativePath.startsWith('/')) {
+    relativePath = "./".concat(relativePath);
+  }
+  return relativePath;
+}
+/**
+ * Extracts the generic type argument from a `visitExample<...>(...)` call expression
+ * using the AST directly (no regex on source text).
+ *
+ * Returns:
+ *   { type: 'inline', importPath } — for `visitExample<typeof import('...')>(...)`
+ *   { type: 'alias', name }        — for `visitExample<SomeTypeAlias>(...)`
+ *   null                           — if no generic type parameter is present
+ */
+function extractGenericType(node) {
+  var _params, _ref, _node$typeArguments;
+  // `typeArguments` is the current property name; `typeParameters` is the deprecated alias.
+  // We fall back to `typeParameters` for compatibility with older parser versions.
+  var params = (_params = (_ref = (_node$typeArguments = node.typeArguments) !== null && _node$typeArguments !== void 0 ? _node$typeArguments : node.typeParameters) === null || _ref === void 0 ? void 0 : _ref.params) !== null && _params !== void 0 ? _params : [];
+  if (params.length === 0) {
+    return null;
+  }
+  var _params2 = (0, _slicedToArray2.default)(params, 1),
+    typeParam = _params2[0];
+
+  // `typeof import('...')` → TSTypeQuery { exprName: TSImportType { ... } }
+  if (typeParam.type === _utils.AST_NODE_TYPES.TSTypeQuery) {
+    var importPath = extractImportPathFromTypeQuery(typeParam);
+    if (importPath !== null) {
+      return {
+        type: 'inline',
+        importPath: importPath
+      };
+    }
+  }
+
+  // `SomeTypeAlias` → TSTypeReference { typeName: Identifier { name } }
+  if (typeParam.type === _utils.AST_NODE_TYPES.TSTypeReference && typeParam.typeName.type === _utils.AST_NODE_TYPES.Identifier) {
+    return {
+      type: 'alias',
+      name: typeParam.typeName.name
+    };
+  }
+  return null;
+}
+var rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Ensures that visitExample uses a typeof import(...) generic and that the import path matches the example file resolved from the call arguments.'
+    },
+    fixable: 'code',
+    messages: messages,
+    schema: []
+  },
+  create: function create(context) {
+    var filename = context.filename;
+    var ast = context.sourceCode.ast;
+    var programBody = ast.body;
+
+    // Build the type alias map once per file (lazily on first visitExample call)
+    var typeAliases = null;
+    function getTypeAliases() {
+      if (!typeAliases) {
+        typeAliases = collectTypeAliases(ast);
+      }
+      return typeAliases;
+    }
+    var variableCache = new Map();
+    return {
+      CallExpression: function CallExpression(estreeNode) {
+        if (!isTargetFile(filename)) {
+          return;
+        }
+        var node = estreeNode;
+        // Only handle `<anything>.visitExample(...)` calls
+        if (node.callee.type !== _utils.AST_NODE_TYPES.MemberExpression || node.callee.property.type !== _utils.AST_NODE_TYPES.Identifier || node.callee.property.name !== 'visitExample') {
+          return;
+        }
+
+        // Narrow callee — we've confirmed property is an Identifier above
+        var callee = node.callee;
+        // reportCallee is typed as estree.Node for context.report compatibility
+        var reportCallee = estreeNode.callee;
+        var genericType = extractGenericType(node);
+
+        // ── Case 1: No generic type parameter ────────────────────────────────
+        if (genericType === null) {
+          var _args = extractCallArgs(node, programBody, variableCache);
+          context.report({
+            node: reportCallee,
+            messageId: 'missingTypeofImport',
+            fix: function fix(fixer) {
+              if (!_args) {
+                return null;
+              }
+              var examplePath = resolveExamplePathFromArgs(_args.groupId, _args.packageId, _args.exampleId, filename);
+              if (!examplePath) {
+                return null;
+              }
+              var importPath = computeRelativeImportPath(filename, examplePath);
+              var _ref2 = callee.property.range,
+                _ref3 = (0, _slicedToArray2.default)(_ref2, 2),
+                start = _ref3[0],
+                end = _ref3[1];
+              return fixer.insertTextAfterRange([start, end], "<typeof import('".concat(importPath, "')>"));
+            }
+          });
+          return;
+        }
+
+        // ── Case 2: Generic is a type alias reference (`visitExample<Foo>`) ──
+        var importPath;
+        if (genericType.type === 'alias') {
+          var found = getTypeAliases().get(genericType.name);
+          if (!found) {
+            // Unknown type alias — not a typeof import
+            context.report({
+              node: reportCallee,
+              messageId: 'missingTypeofImport'
+            });
+            return;
+          }
+          if (found.isFileLevel) {
+            // Top-level `type Foo = typeof import(...)` is disallowed
+            context.report({
+              node: reportCallee,
+              messageId: 'typeAliasNotInlined'
+            });
+            return;
+          }
+          var typeAnnotation = found.node.typeAnnotation;
+          if (typeAnnotation.type !== _utils.AST_NODE_TYPES.TSTypeQuery) {
+            context.report({
+              node: reportCallee,
+              messageId: 'missingTypeofImport'
+            });
+            return;
+          }
+          var resolved = extractImportPathFromTypeQuery(typeAnnotation);
+          if (!resolved) {
+            context.report({
+              node: reportCallee,
+              messageId: 'missingTypeofImport'
+            });
+            return;
+          }
+          importPath = resolved;
+        } else {
+          // ── Case 3: Inline `typeof import('...')` ────────────────────────
+          importPath = genericType.importPath;
+        }
+
+        // Package-scoped imports (e.g. @atlaskit/foo/examples/...) are not allowed
+        if (importPath.startsWith('@')) {
+          context.report({
+            node: reportCallee,
+            messageId: 'noPackageImports'
+          });
+          return;
+        }
+
+        // Validate that the import path matches the arguments
+        var args = extractCallArgs(node, programBody, variableCache);
+        if (!args) {
+          // Dynamic arguments — can't validate statically
+          return;
+        }
+        var expectedPath = resolveExamplePathFromArgs(args.groupId, args.packageId, args.exampleId, filename);
+        if (!expectedPath) {
+          return;
+        }
+        var resolvedImport = _path.default.normalize(_path.default.resolve(_path.default.dirname(filename), importPath));
+        var resolvedExpected = _path.default.normalize(expectedPath);
+
+        // Compare without extensions so `.tsx` vs no extension doesn't matter
+        if (resolvedImport.replace(/\.(tsx?|jsx?)$/, '') !== resolvedExpected.replace(/\.(tsx?|jsx?)$/, '')) {
+          context.report({
+            node: estreeNode.arguments[0],
+            messageId: 'pathMismatch',
+            data: {
+              importPath: importPath,
+              groupId: args.groupId,
+              packageId: args.packageId,
+              exampleId: args.exampleId,
+              expectedPath: resolvedExpected
+            },
+            fix: function fix(fixer) {
+              var _node$typeArguments2;
+              var correctedPath = computeRelativeImportPath(filename, resolvedExpected);
+              var typeParams = (_node$typeArguments2 = node.typeArguments) !== null && _node$typeArguments2 !== void 0 ? _node$typeArguments2 : node.typeParameters;
+              if (!(typeParams !== null && typeParams !== void 0 && typeParams.range)) {
+                return null;
+              }
+              return fixer.replaceTextRange(typeParams.range, "<typeof import('".concat(correctedPath, "')>"));
+            }
+          });
+        }
+      }
+    };
+  }
+};
+var _default = exports.default = rule;

package/dist/es2019/index.js

@@ -34,6 +34,8 @@ import noBarrelEntryJestMock from './rules/import/no-barrel-entry-jest-mock';
 import noJestMockBarrelFiles from './rules/import/no-jest-mock-barrel-files';
 import noRelativeBarrelFileImports from './rules/import/no-relative-barrel-file-imports';
 import noConversationAssistantBarrelImports from './rules/import/no-conversation-assistant-barrel-imports';
+import visitExampleTypeImportRequired from './rules/visit-example-type-import-required';
+import ensureUseSyncExternalStoreServerSnapshot from './rules/ensure-use-sync-external-store-server-snapshot';
 import { join, normalize } from 'node:path';
 import { readFileSync } from 'node:fs';
 let jiraRoot;
@@ -87,11 +89,14 @@ const rules = {
   'no-barrel-entry-jest-mock': noBarrelEntryJestMock,
   'no-jest-mock-barrel-files': noJestMockBarrelFiles,
   'no-relative-barrel-file-imports': noRelativeBarrelFileImports,
-  'no-conversation-assistant-barrel-imports': noConversationAssistantBarrelImports
+  'no-conversation-assistant-barrel-imports': noConversationAssistantBarrelImports,
+  'visit-example-type-import-required': visitExampleTypeImportRequired,
+  'ensure-use-sync-external-store-server-snapshot': ensureUseSyncExternalStoreServerSnapshot
 };
 const commonConfig = {
   '@atlaskit/platform/ensure-test-runner-arguments': 'error',
   '@atlaskit/platform/ensure-test-runner-nested-count': 'warn',
+  '@atlaskit/platform/ensure-use-sync-external-store-server-snapshot': 'error',
   '@atlaskit/platform/no-invalid-feature-flag-usage': 'error',
   '@atlaskit/platform/no-invalid-storybook-decorator-usage': 'error',
   '@atlaskit/platform/ensure-atlassian-team': 'error',

package/dist/es2019/rules/ensure-use-sync-external-store-server-snapshot/index.js

@@ -0,0 +1,43 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+
+const FUNCTION_NAME = 'useSyncExternalStore';
+const rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: `Enforce that ${FUNCTION_NAME} is called with a third argument (getServerSnapshot) for SSR compatibility`,
+      recommended: true
+    },
+    messages: {
+      missingServerSnapshot: `'${FUNCTION_NAME}' must be called with a third argument (getServerSnapshot). Without it, React will throw during server-side rendering.
+
+If your component relies on browser-only APIs (e.g. localStorage, WebRTC, WebGL) and must not render on the server, pass \`() => null\` (or another stable fallback) as the third argument — this is the correct way to opt out of SSR, not an omission.
+
+Prefer higher-level APIs that wrap ${FUNCTION_NAME} where available, as they handle SSR concerns for you.
+
+See the React docs for usage guidance: https://react.dev/reference/react/useSyncExternalStore`
+    }
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        const {
+          callee,
+          arguments: args
+        } = node;
+        const isDirectCall = callee.type === 'Identifier' && callee.name === FUNCTION_NAME;
+        const isMemberCall = callee.type === 'MemberExpression' && callee.property.type === 'Identifier' && callee.property.name === FUNCTION_NAME;
+        if (!isDirectCall && !isMemberCall) {
+          return;
+        }
+        if (args.length < 3) {
+          context.report({
+            node,
+            messageId: 'missingServerSnapshot'
+          });
+        }
+      }
+    };
+  }
+};
+export default rule;