@atlaskit/eslint-plugin-platform 2.8.0 → 2.9.0

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

@@ -0,0 +1,375 @@
+import fs from 'fs';
+import path from 'path';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+import { simpleTraverse } from '@typescript-eslint/typescript-estree';
+export const RULE_NAME = 'visit-example-type-import-required';
+const 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 } } }
+  const {
+    exprName
+  } = typeQuery;
+  if (exprName.type !== AST_NODE_TYPES.TSImportType) {
+    return null;
+  }
+  const {
+    argument
+  } = exprName;
+  if (argument.type === AST_NODE_TYPES.TSLiteralType && argument.literal.type === 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) {
+  const 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.
+  simpleTraverse(ast, {
+    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 === AST_NODE_TYPES.TSTypeAliasDeclaration) {
+        const isFileLevel = (parent === null || parent === void 0 ? void 0 : parent.type) === AST_NODE_TYPES.Program || (parent === null || parent === void 0 ? void 0 : parent.type) === AST_NODE_TYPES.ExportNamedDeclaration;
+        result.set(node.id.name, {
+          node: node,
+          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;
+  }
+  for (const node of programBody) {
+    if (node.type !== AST_NODE_TYPES.VariableDeclaration || node.kind !== 'const') {
+      continue;
+    }
+    for (const declarator of node.declarations) {
+      var _declarator$init;
+      if (declarator.id.type === AST_NODE_TYPES.Identifier && declarator.id.name === variableName && ((_declarator$init = declarator.init) === null || _declarator$init === void 0 ? void 0 : _declarator$init.type) === AST_NODE_TYPES.Literal && typeof declarator.init.value === 'string') {
+        cache.set(variableName, declarator.init.value);
+        return declarator.init.value;
+      }
+    }
+  }
+  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 === AST_NODE_TYPES.Literal && typeof arg.value === 'string') {
+      return arg.value;
+    }
+    if (arg.type === AST_NODE_TYPES.Identifier) {
+      return resolveVariableToConstant(programBody, arg.name, variableCache);
+    }
+    return null;
+  }
+  const groupId = resolveArg(node.arguments[0]);
+  const packageId = resolveArg(node.arguments[1]);
+  const exampleId = resolveArg(node.arguments[2]);
+  if (!groupId || !packageId || !exampleId) {
+    return null;
+  }
+  return {
+    groupId,
+    packageId,
+    exampleId
+  };
+}
+function getPackagesBasePath(testFilePath) {
+  const testFileDir = path.dirname(testFilePath);
+  const testFileSegments = testFileDir.split(path.sep);
+  const packagesIndex = testFileSegments.findIndex(seg => seg === 'packages');
+  if (packagesIndex === -1) {
+    return null;
+  }
+  const baseSegments = testFileSegments.slice(0, packagesIndex + 1);
+  const basePath = path.isAbsolute(testFilePath) ? path.resolve('/', ...baseSegments) : path.resolve(process.cwd(), ...baseSegments);
+  return {
+    basePath,
+    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) {
+  const packagesBase = getPackagesBasePath(testFilePath);
+  if (!packagesBase) {
+    return null;
+  }
+  const examplesDir = path.resolve(packagesBase.basePath, groupId, packageId, 'examples');
+  const fallback = path.resolve(examplesDir, `${exampleId}.tsx`);
+
+  // Match: exact name OR numeric-prefixed variant, with optional `.examples` infix
+  const candidateRe = new RegExp(`^(?:\\d+-)?${exampleId}(?:\\.examples?)?\\.tsx$`);
+  try {
+    const match = fs.readdirSync(examplesDir).find(f => candidateRe.test(f));
+    if (match) {
+      return path.resolve(examplesDir, match);
+    }
+  } catch {
+    // 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) {
+  const fromDir = path.dirname(fromFile);
+  let relativePath = path.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 = `./${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.
+  const 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;
+  }
+  const [typeParam] = params;
+
+  // `typeof import('...')` → TSTypeQuery { exprName: TSImportType { ... } }
+  if (typeParam.type === AST_NODE_TYPES.TSTypeQuery) {
+    const importPath = extractImportPathFromTypeQuery(typeParam);
+    if (importPath !== null) {
+      return {
+        type: 'inline',
+        importPath
+      };
+    }
+  }
+
+  // `SomeTypeAlias` → TSTypeReference { typeName: Identifier { name } }
+  if (typeParam.type === AST_NODE_TYPES.TSTypeReference && typeParam.typeName.type === AST_NODE_TYPES.Identifier) {
+    return {
+      type: 'alias',
+      name: typeParam.typeName.name
+    };
+  }
+  return null;
+}
+const 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,
+    schema: []
+  },
+  create(context) {
+    const filename = context.filename;
+    const ast = context.sourceCode.ast;
+    const programBody = ast.body;
+
+    // Build the type alias map once per file (lazily on first visitExample call)
+    let typeAliases = null;
+    function getTypeAliases() {
+      if (!typeAliases) {
+        typeAliases = collectTypeAliases(ast);
+      }
+      return typeAliases;
+    }
+    const variableCache = new Map();
+    return {
+      CallExpression(estreeNode) {
+        if (!isTargetFile(filename)) {
+          return;
+        }
+        const node = estreeNode;
+        // Only handle `<anything>.visitExample(...)` calls
+        if (node.callee.type !== AST_NODE_TYPES.MemberExpression || node.callee.property.type !== AST_NODE_TYPES.Identifier || node.callee.property.name !== 'visitExample') {
+          return;
+        }
+
+        // Narrow callee — we've confirmed property is an Identifier above
+        const callee = node.callee;
+        // reportCallee is typed as estree.Node for context.report compatibility
+        const reportCallee = estreeNode.callee;
+        const genericType = extractGenericType(node);
+
+        // ── Case 1: No generic type parameter ────────────────────────────────
+        if (genericType === null) {
+          const args = extractCallArgs(node, programBody, variableCache);
+          context.report({
+            node: reportCallee,
+            messageId: 'missingTypeofImport',
+            fix(fixer) {
+              if (!args) {
+                return null;
+              }
+              const examplePath = resolveExamplePathFromArgs(args.groupId, args.packageId, args.exampleId, filename);
+              if (!examplePath) {
+                return null;
+              }
+              const importPath = computeRelativeImportPath(filename, examplePath);
+              const [start, end] = callee.property.range;
+              return fixer.insertTextAfterRange([start, end], `<typeof import('${importPath}')>`);
+            }
+          });
+          return;
+        }
+
+        // ── Case 2: Generic is a type alias reference (`visitExample<Foo>`) ──
+        let importPath;
+        if (genericType.type === 'alias') {
+          const 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;
+          }
+          const typeAnnotation = found.node.typeAnnotation;
+          if (typeAnnotation.type !== AST_NODE_TYPES.TSTypeQuery) {
+            context.report({
+              node: reportCallee,
+              messageId: 'missingTypeofImport'
+            });
+            return;
+          }
+          const 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
+        const args = extractCallArgs(node, programBody, variableCache);
+        if (!args) {
+          // Dynamic arguments — can't validate statically
+          return;
+        }
+        const expectedPath = resolveExamplePathFromArgs(args.groupId, args.packageId, args.exampleId, filename);
+        if (!expectedPath) {
+          return;
+        }
+        const resolvedImport = path.normalize(path.resolve(path.dirname(filename), importPath));
+        const resolvedExpected = path.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,
+              groupId: args.groupId,
+              packageId: args.packageId,
+              exampleId: args.exampleId,
+              expectedPath: resolvedExpected
+            },
+            fix(fixer) {
+              var _node$typeArguments2;
+              const correctedPath = computeRelativeImportPath(filename, resolvedExpected);
+              const 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('${correctedPath}')>`);
+            }
+          });
+        }
+      }
+    };
+  }
+};
+export default rule;

package/dist/esm/index.js

@@ -37,6 +37,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';
 var jiraRoot;
@@ -90,11 +92,14 @@ var 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
 };
 var 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/esm/rules/ensure-use-sync-external-store-server-snapshot/index.js

@@ -0,0 +1,35 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+
+var FUNCTION_NAME = 'useSyncExternalStore';
+var rule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: "Enforce that ".concat(FUNCTION_NAME, " is called with a third argument (getServerSnapshot) for SSR compatibility"),
+      recommended: true
+    },
+    messages: {
+      missingServerSnapshot: "'".concat(FUNCTION_NAME, "' must be called with a third argument (getServerSnapshot). Without it, React will throw during server-side rendering.\n\nIf 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 \u2014 this is the correct way to opt out of SSR, not an omission.\n\nPrefer higher-level APIs that wrap ").concat(FUNCTION_NAME, " where available, as they handle SSR concerns for you.\n\nSee the React docs for usage guidance: https://react.dev/reference/react/useSyncExternalStore")
+    }
+  },
+  create: function create(context) {
+    return {
+      CallExpression: function CallExpression(node) {
+        var callee = node.callee,
+          args = node.arguments;
+        var isDirectCall = callee.type === 'Identifier' && callee.name === FUNCTION_NAME;
+        var isMemberCall = callee.type === 'MemberExpression' && callee.property.type === 'Identifier' && callee.property.name === FUNCTION_NAME;
+        if (!isDirectCall && !isMemberCall) {
+          return;
+        }
+        if (args.length < 3) {
+          context.report({
+            node: node,
+            messageId: 'missingServerSnapshot'
+          });
+        }
+      }
+    };
+  }
+};
+export default rule;