@medplum/eslint-config 5.1.17 → 5.1.21

package/index.mjs

@@ -7,13 +7,21 @@ import importPlugin from 'eslint-plugin-import';
 import jsdoc from 'eslint-plugin-jsdoc';
 import noOnlyTestsPlugin from 'eslint-plugin-no-only-tests';
 import reactHooks from 'eslint-plugin-react-hooks';
-import reactRefresh from 'eslint-plugin-react-refresh';
+import reactRefreshPlugin from 'eslint-plugin-react-refresh';
+// eslint-disable-next-line import/no-unresolved -- Node resolves this package export; eslint-plugin-import does not.
 import tseslint from 'typescript-eslint';
+import noTransactionCallbackInvokingRepo from './rules/no-transaction-callback-invoking-repo.mjs';
 
 // Workaround for eslint-plugin-header ESLint 9 compatibility issue.
 // See: https://github.com/Stuk/eslint-plugin-header/issues/57#issuecomment-2378485611
 headerPlugin.rules.header.meta.schema = false;
 
+const medplumPlugin = {
+  rules: {
+    'no-transaction-callback-invoking-repo': noTransactionCallbackInvokingRepo,
+  },
+};
+
 /**
  * Core config applies to all source files.
  * TypeScript-specific rules are in the tsConfig below.
@@ -147,7 +155,7 @@ export const tsConfig = {
     },
     tseslint.configs.strict,
     reactHooks.configs.flat.recommended,
-    reactRefresh.configs.recommended,
+    reactRefreshPlugin.configs.recommended,
   ],
   plugins: {
     'no-only-tests': noOnlyTestsPlugin,
@@ -295,13 +303,23 @@ export const medplumEslintConfig = [
   },
   coreConfig,
   tsConfig,
+  {
+    files: ['packages/fhir-router/**/*.ts', 'packages/server/**/*.ts'],
+    plugins: {
+      medplum: medplumPlugin,
+    },
+    rules: {
+      'medplum/no-transaction-callback-invoking-repo': 'error',
+    },
+  },
   /**
-   * vite.config.ts is often outside package tsconfig include (e.g. rootDir src); skip type-aware parsing.
+   * vite.config.ts and vitest.config.ts are often outside package tsconfig include (e.g. rootDir src);
+   * skip type-aware parsing.
    *
-   * we don't need type checking for vite.config.ts files
+   * we don't need type checking for vite.config.ts or vitest.config.ts files
    */
   {
-    files: ['**/vite.config.ts'],
+    files: ['**/vite.config.ts', '**/vitest.config.ts'],
     extends: [tseslint.configs.disableTypeChecked],
   },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medplum/eslint-config",
-  "version": "5.1.17",
+  "version": "5.1.21",
   "description": "Shared ESLint configuration for Medplum projects",
   "keywords": [
     "eslint",
@@ -19,15 +19,20 @@
   "author": "Medplum <hello@medplum.com>",
   "type": "module",
   "main": "index.mjs",
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "node --test rules/*.test.mjs"
+  },
   "devDependencies": {
     "eslint": "9.39.4",
     "eslint-plugin-header": "3.1.1",
     "eslint-plugin-import": "2.32.0",
-    "eslint-plugin-jsdoc": "63.0.1",
+    "eslint-plugin-jsdoc": "63.0.2",
     "eslint-plugin-no-only-tests": "3.4.0",
     "eslint-plugin-react-hooks": "7.1.1",
     "eslint-plugin-react-refresh": "0.5.2",
-    "typescript-eslint": "8.60.1"
+    "typescript-eslint": "8.61.0"
   },
   "peerDependencies": {
     "eslint": "^9",

package/rules/no-transaction-callback-invoking-repo.mjs

@@ -0,0 +1,311 @@
+// SPDX-FileCopyrightText: Copyright Orangebot, Inc. and Medplum contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Flags uses of the repository that a `withTransaction`/`ensureInTransaction` callback was
+ * invoked on from inside that callback, including aliasing it (`const parent = repo`).
+ * Callback code must use the transaction-scoped repository passed as the callback parameter;
+ * the invoking repository is locked for the duration of the transaction and throws at runtime.
+ *
+ * This rule is fast feedback for the common cases, not the enforcement mechanism. The
+ * runtime scope guard in RepositoryConnection.assertScope() is authoritative. Known blind
+ * spots, deliberately left uncovered because closing them requires transitive variable
+ * resolution that is not worth the complexity:
+ * - Aliases created before the callback: `const r = repo; repo.withTransaction(() => r.foo())`
+ * - Reassignment through a mutable binding: `let r; r = repo;`
+ * - The repo escaping through a function argument, property, or field, e.g. the
+ *   `this.repo` swap in BatchProcessor.withRepo() in fhir-router's batch.ts
+ * - When the invoking repo is reached through `this`, the rule stops descending at
+ *   constructs that rebind `this` (non-arrow functions, classes), so a computed class
+ *   member key that evaluates with the outer `this` is missed
+ */
+const transactionMethodNames = new Set(['withTransaction', 'ensureInTransaction']);
+const thisRebindingNodeTypes = new Set([
+  'ClassDeclaration',
+  'ClassExpression',
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'StaticBlock',
+]);
+const ignoredTraversalKeys = new Set([
+  'comments',
+  'decorators',
+  'loc',
+  'parent',
+  'range',
+  'returnType',
+  'tokens',
+  'typeAnnotation',
+  'typeArguments',
+  'typeParameters',
+]);
+
+/**
+ * @param context - ESLint rule context.
+ * @returns ESLint rule listener.
+ */
+function create(context) {
+  const sourceCode = context.sourceCode;
+
+  /**
+   * @param node - The AST node.
+   * @returns The unwrapped expression.
+   */
+  function unwrapExpression(node) {
+    let result = node;
+    while (
+      result?.type === 'ChainExpression' ||
+      result?.type === 'TSAsExpression' ||
+      result?.type === 'TSNonNullExpression' ||
+      result?.type === 'TSTypeAssertion'
+    ) {
+      result = result.expression;
+    }
+    return result;
+  }
+
+  /**
+   * @param node - The AST node.
+   * @returns The scope for the AST node.
+   */
+  function getScope(node) {
+    return sourceCode.getScope(node);
+  }
+
+  /**
+   * @param node - The identifier node.
+   * @returns The variable represented by the identifier.
+   */
+  function findVariable(node) {
+    let scope = getScope(node);
+    while (scope) {
+      const variable = scope.set.get(node.name);
+      if (variable) {
+        return variable;
+      }
+      scope = scope.upper;
+    }
+    return undefined;
+  }
+
+  /**
+   * @param node - The identifier node.
+   * @returns True if the identifier is an expression reference.
+   */
+  function isReferenceIdentifier(node) {
+    const parent = node.parent;
+    if (!parent) {
+      return true;
+    }
+
+    switch (parent.type) {
+      case 'ArrayPattern':
+      case 'ImportDefaultSpecifier':
+      case 'ImportNamespaceSpecifier':
+      case 'LabeledStatement':
+      case 'MetaProperty':
+      case 'RestElement':
+      case 'TSTypeReference':
+        return false;
+      case 'VariableDeclarator':
+        // The declared name is not a reference, but the initializer is:
+        // `const alias = repo` reads the repo to create an alias for it
+        return parent.init === node;
+      case 'AssignmentPattern':
+        return parent.right === node;
+      case 'ClassDeclaration':
+      case 'ClassExpression':
+      case 'FunctionDeclaration':
+      case 'FunctionExpression':
+        return parent.id !== node;
+      case 'ImportSpecifier':
+        return parent.local !== node;
+      case 'MemberExpression':
+        return parent.object === node || parent.computed;
+      case 'MethodDefinition':
+      case 'Property':
+      case 'PropertyDefinition':
+        return parent.value === node || parent.computed;
+      default:
+        return true;
+    }
+  }
+
+  /**
+   * @param node - The member expression.
+   * @returns The static property name.
+   */
+  function getStaticPropertyName(node) {
+    if (node.computed) {
+      const property = unwrapExpression(node.property);
+      return property?.type === 'Literal' && typeof property.value === 'string' ? property.value : undefined;
+    }
+    if (node.property.type === 'Identifier' || node.property.type === 'PrivateIdentifier') {
+      return node.property.name;
+    }
+    return undefined;
+  }
+
+  /**
+   * @param expected - The expected member expression.
+   * @param candidate - The candidate member expression.
+   * @returns True if the member expressions use the same property.
+   */
+  function hasSameProperty(expected, candidate) {
+    if (expected.computed || candidate.computed) {
+      return (
+        expected.computed === candidate.computed &&
+        sourceCode.getText(expected.property) === sourceCode.getText(candidate.property)
+      );
+    }
+    return getStaticPropertyName(expected) === getStaticPropertyName(candidate);
+  }
+
+  /**
+   * @param expected - The expected expression.
+   * @param candidate - The candidate expression.
+   * @returns True if both expressions refer to the same expression.
+   */
+  function isSameExpression(expected, candidate) {
+    const unwrappedExpected = unwrapExpression(expected);
+    const unwrappedCandidate = unwrapExpression(candidate);
+    if (!unwrappedExpected || !unwrappedCandidate || unwrappedExpected.type !== unwrappedCandidate.type) {
+      return false;
+    }
+
+    switch (unwrappedExpected.type) {
+      case 'Identifier':
+        return (
+          isReferenceIdentifier(unwrappedCandidate) &&
+          unwrappedExpected.name === unwrappedCandidate.name &&
+          findVariable(unwrappedExpected) === findVariable(unwrappedCandidate)
+        );
+      case 'ThisExpression':
+        return true;
+      case 'Super':
+        return true;
+      case 'MemberExpression':
+        return (
+          hasSameProperty(unwrappedExpected, unwrappedCandidate) &&
+          isSameExpression(unwrappedExpected.object, unwrappedCandidate.object)
+        );
+      default:
+        return sourceCode.getText(unwrappedExpected) === sourceCode.getText(unwrappedCandidate);
+    }
+  }
+
+  /**
+   * @param node - The AST node.
+   * @returns True if the node is a function expression.
+   */
+  function isCallbackFunction(node) {
+    return node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression';
+  }
+
+  /**
+   * @param node - The AST node.
+   * @param callback - The visitor callback.
+   * @param skipThisRebinding - Whether to stop descending at nodes that rebind `this`.
+   */
+  function visit(node, callback, skipThisRebinding = false) {
+    if (callback(node)) {
+      return;
+    }
+    if (skipThisRebinding && thisRebindingNodeTypes.has(node.type)) {
+      return;
+    }
+
+    for (const [key, value] of Object.entries(node)) {
+      if (ignoredTraversalKeys.has(key)) {
+        continue;
+      }
+      if (Array.isArray(value)) {
+        for (const child of value) {
+          if (child?.type) {
+            visit(child, callback, skipThisRebinding);
+          }
+        }
+      } else if (value?.type) {
+        visit(value, callback, skipThisRebinding);
+      }
+    }
+  }
+
+  /**
+   * @param node - The AST node.
+   * @returns True if the expression contains a `this` or `super` reference.
+   */
+  function usesThisBinding(node) {
+    let found = false;
+    visit(node, (candidate) => {
+      if (candidate.type === 'ThisExpression' || candidate.type === 'Super') {
+        found = true;
+      }
+      return found;
+    });
+    return found;
+  }
+
+  return {
+    CallExpression(node) {
+      const callee = unwrapExpression(node.callee);
+      if (callee?.type !== 'MemberExpression') {
+        return;
+      }
+
+      const methodName = getStaticPropertyName(callee);
+      if (!methodName || !transactionMethodNames.has(methodName)) {
+        return;
+      }
+
+      const invokingRepo = unwrapExpression(callee.object);
+      const callback = unwrapExpression(node.arguments[0]);
+      if (!invokingRepo || !callback || !isCallbackFunction(callback)) {
+        return;
+      }
+
+      const repoUsesThis = usesThisBinding(invokingRepo);
+      if (repoUsesThis && callback.type === 'FunctionExpression') {
+        // A non-arrow callback rebinds `this`, so the invoking repo is unreachable inside it
+        return;
+      }
+
+      visit(
+        callback.body,
+        (candidate) => {
+          if (!isSameExpression(invokingRepo, candidate)) {
+            return false;
+          }
+
+          context.report({
+            node: candidate,
+            messageId: 'useCallbackRepo',
+            data: {
+              methodName,
+              repoName: sourceCode.getText(invokingRepo),
+            },
+          });
+          return true;
+        },
+        repoUsesThis
+      );
+    },
+  };
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noTransactionCallbackInvokingRepoRule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'require transaction callbacks to use the repository parameter instead of the invoking repository',
+    },
+    messages: {
+      useCallbackRepo: 'Use the repository passed to the {{methodName}} callback instead of `{{repoName}}`.',
+    },
+    schema: [],
+  },
+  create,
+};
+
+export default noTransactionCallbackInvokingRepoRule;

package/rules/no-transaction-callback-invoking-repo.test.mjs

@@ -0,0 +1,146 @@
+// SPDX-FileCopyrightText: Copyright Orangebot, Inc. and Medplum contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { RuleTester } from 'eslint';
+import rule from './no-transaction-callback-invoking-repo.mjs';
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+  },
+});
+
+ruleTester.run('no-transaction-callback-invoking-repo', rule, {
+  valid: [
+    {
+      code: 'repo.withTransaction(async (txRepo) => txRepo.createResource(resource));',
+    },
+    {
+      code: 'repo.ensureInTransaction(async (txRepo) => txRepo.createResource(resource));',
+    },
+    {
+      code: 'ctx.repo.withTransaction(async (txRepo) => txRepo.createResource(resource));',
+    },
+    {
+      code: 'this.repo.withTransaction(async (txRepo) => this.withRepo(txRepo, () => this.processBatch()));',
+    },
+    {
+      code: 'repo.withTransaction(async (repo) => repo.createResource(resource));',
+    },
+    {
+      code: 'repo.withTransaction(txFn);',
+    },
+    {
+      code: [
+        'repo.withTransaction(async (txRepo) =>',
+        '  txRepo.withTransaction(async (nestedRepo) => nestedRepo.createResource(resource))',
+        ');',
+      ].join('\n'),
+    },
+    {
+      // Declaring a shadowing variable from the callback repo is fine; only the
+      // initializer of a declaration counts as a reference, not the declared name
+      code: [
+        'repo.withTransaction(async (txRepo) => {',
+        '  const repo = txRepo;',
+        '  return repo.createResource(resource);',
+        '});',
+      ].join('\n'),
+    },
+    {
+      // `this` inside a nested non-arrow function is a different binding
+      code: [
+        'this.repo.withTransaction(async (txRepo) => {',
+        '  emitter.on("done", function () {',
+        '    this.repo.createResource(resource);',
+        '  });',
+        '});',
+      ].join('\n'),
+    },
+    {
+      // `this` inside a nested class method is a different binding
+      code: [
+        'this.repo.withTransaction(async (txRepo) => {',
+        '  class Helper {',
+        '    run() {',
+        '      return this.repo.createResource(resource);',
+        '    }',
+        '  }',
+        '  return new Helper().run();',
+        '});',
+      ].join('\n'),
+    },
+    {
+      // A non-arrow callback rebinds `this`, so the invoking repo is unreachable inside it
+      code: 'this.repo.withTransaction(async function (txRepo) { return this.repo.createResource(resource); });',
+    },
+  ],
+  invalid: [
+    {
+      code: 'repo.withTransaction(async (txRepo) => repo.createResource(resource));',
+      errors: [{ messageId: 'useCallbackRepo' }],
+    },
+    {
+      code: 'repo.ensureInTransaction(async (txRepo) => repo.createResource(resource));',
+      errors: [{ messageId: 'useCallbackRepo' }],
+    },
+    {
+      code: 'ctx.repo.withTransaction(async (txRepo) => ctx.repo.createResource(resource));',
+      errors: [{ messageId: 'useCallbackRepo' }],
+    },
+    {
+      code: 'this.repo.withTransaction(async (txRepo) => this.repo.createResource(resource));',
+      errors: [{ messageId: 'useCallbackRepo' }],
+    },
+    {
+      code: [
+        'repo.withTransaction(async (txRepo) =>',
+        '  repo.withTransaction(async (nestedRepo) => nestedRepo.createResource(resource))',
+        ');',
+      ].join('\n'),
+      errors: [{ messageId: 'useCallbackRepo' }],
+    },
+    {
+      // Aliasing the invoking repo inside the callback is flagged at the alias declaration
+      code: [
+        'repo.withTransaction(async (txRepo) => {',
+        '  const parent = repo;',
+        '  return parent.createResource(resource);',
+        '});',
+      ].join('\n'),
+      errors: [{ messageId: 'useCallbackRepo' }],
+    },
+    {
+      code: [
+        'ctx.repo.withTransaction(async (txRepo) => {',
+        '  const parent = ctx.repo;',
+        '  return parent.createResource(resource);',
+        '});',
+      ].join('\n'),
+      errors: [{ messageId: 'useCallbackRepo' }],
+    },
+    {
+      // Arrow functions inherit `this`, so the invoking repo is still reachable
+      code: [
+        'this.repo.withTransaction(async (txRepo) => {',
+        '  const run = () => this.repo.createResource(resource);',
+        '  return run();',
+        '});',
+      ].join('\n'),
+      errors: [{ messageId: 'useCallbackRepo' }],
+    },
+    {
+      // Identifier resolution is unaffected by `this` rebinding in nested functions
+      code: [
+        'repo.withTransaction(async (txRepo) => {',
+        '  function helper() {',
+        '    return repo.createResource(resource);',
+        '  }',
+        '  return helper();',
+        '});',
+      ].join('\n'),
+      errors: [{ messageId: 'useCallbackRepo' }],
+    },
+  ],
+});