@checkdigit/eslint-plugin 7.2.0 → 7.3.0-PR.75-aa6d

package/src/agent/fetch-then.ts

@@ -0,0 +1,355 @@
+// agent/fetch-then.ts
+
+/*
+ * Copyright (c) 2021-2024 Check Digit, LLC
+ *
+ * This code is licensed under the MIT license (see LICENSE.txt for details).
+ */
+
+import { strict as assert } from 'node:assert';
+
+import type { CallExpression, Expression, MemberExpression, SimpleCallExpression } from 'estree';
+import { type Rule, type Scope, SourceCode } from 'eslint';
+
+import { getEnclosingFunction, getEnclosingStatement, getParent, isUsedInArrayOrAsArgument } from '../library/tree';
+import getDocumentationUrl from '../get-documentation-url';
+import { getIndentation } from '../library/format';
+import { isValidPropertyName } from '../library/variable';
+import { hasAssertions, isInvalidResponseHeadersAccess } from './fetch';
+import { replaceEndpointUrlPrefixWithBasePath } from './url';
+
+export const ruleId = 'fetch-then';
+
+interface FixtureCallInformation {
+  fixtureNode: SimpleCallExpression;
+  requestBody?: Expression;
+  requestHeaders?: { name: Expression; value: Expression }[];
+  assertions?: Expression[][];
+}
+
+// recursively analyze the fixture/supertest call chain to collect information of request/response
+function analyzeFixtureCall(call: SimpleCallExpression, results: FixtureCallInformation, sourceCode: SourceCode) {
+  const parent = getParent(call);
+  if (!parent) {
+    return;
+  }
+
+  let nextCall;
+  if (parent.type !== 'MemberExpression') {
+    results.fixtureNode = call;
+    return;
+  }
+
+  if (parent.property.type === 'Identifier') {
+    if (parent.property.name === 'expect') {
+      // supertest assertions
+      const assertionCall = getParent(parent);
+      assert.ok(assertionCall && assertionCall.type === 'CallExpression');
+      results.assertions = [...(results.assertions ?? []), assertionCall.arguments as Expression[]];
+      nextCall = assertionCall;
+    } else if (parent.property.name === 'send') {
+      // request body
+      const sendRequestBodyCall = getParent(parent);
+      assert.ok(sendRequestBodyCall && sendRequestBodyCall.type === 'CallExpression');
+      results.requestBody = sendRequestBodyCall.arguments[0] as Expression;
+      nextCall = sendRequestBodyCall;
+    } else if (parent.property.name === 'set') {
+      // request headers
+      const setRequestHeaderCall = getParent(parent);
+      assert.ok(setRequestHeaderCall && setRequestHeaderCall.type === 'CallExpression');
+      const [name, value] = setRequestHeaderCall.arguments as [Expression, Expression];
+      results.requestHeaders = [...(results.requestHeaders ?? []), { name, value }];
+      nextCall = setRequestHeaderCall;
+    }
+  } else {
+    throw new Error(`Unexpected expression in fixture/supertest call ${sourceCode.getText(parent)}.`);
+  }
+  if (nextCall) {
+    analyzeFixtureCall(nextCall, results, sourceCode);
+  }
+}
+
+// eslint-disable-next-line sonarjs/cognitive-complexity
+function createResponseAssertions(
+  fixtureCallInformation: FixtureCallInformation,
+  sourceCode: SourceCode,
+  responseVariableName: string,
+) {
+  let statusAssertion: string | undefined;
+  const nonStatusAssertions: string[] = [];
+  for (const expectArguments of fixtureCallInformation.assertions ?? []) {
+    if (expectArguments.length === 1) {
+      const [assertionArgument] = expectArguments;
+      assert.ok(assertionArgument);
+      if (
+        (assertionArgument.type === 'MemberExpression' &&
+          assertionArgument.object.type === 'Identifier' &&
+          assertionArgument.object.name === 'StatusCodes') ||
+        assertionArgument.type === 'Literal' ||
+        sourceCode.getText(assertionArgument).includes('StatusCodes.')
+      ) {
+        // status code assertion
+        statusAssertion = `assert.equal(${responseVariableName}.status, ${sourceCode.getText(assertionArgument)})`;
+      } else if (assertionArgument.type === 'ArrowFunctionExpression') {
+        // callback assertion using arrow function
+        let functionBody = sourceCode.getText(assertionArgument.body);
+
+        const [originalResponseArgument] = assertionArgument.params;
+        assert.ok(originalResponseArgument?.type === 'Identifier');
+        const originalResponseArgumentName = originalResponseArgument.name;
+        if (originalResponseArgumentName !== responseVariableName) {
+          functionBody = functionBody.replace(
+            new RegExp(`\\b${originalResponseArgumentName}\\b`, 'ug'),
+            responseVariableName,
+          );
+        }
+        nonStatusAssertions.push(`assert.ok(${functionBody})`);
+      } else if (assertionArgument.type === 'Identifier') {
+        // callback assertion using function reference
+        nonStatusAssertions.push(`assert.ok(${sourceCode.getText(assertionArgument)}(${responseVariableName}))`);
+      } else if (assertionArgument.type === 'ObjectExpression' || assertionArgument.type === 'CallExpression') {
+        // body deep equal assertion
+        nonStatusAssertions.push(
+          `assert.deepEqual(await ${responseVariableName}.json(), ${sourceCode.getText(assertionArgument)})`,
+        );
+      } else {
+        throw new Error(`Unexpected Supertest assertion argument: ".expect(${sourceCode.getText(assertionArgument)})`);
+      }
+    } else if (expectArguments.length === 2) {
+      // header assertion
+      const [headerName, headerValue] = expectArguments;
+      assert.ok(headerName && headerValue);
+      const headersReference = `${responseVariableName}.headers`;
+      if (headerValue.type === 'Literal' && headerValue.value instanceof RegExp) {
+        nonStatusAssertions.push(
+          `assert.ok(${headersReference}.get(${sourceCode.getText(headerName)}).match(${sourceCode.getText(headerValue)}))`,
+        );
+      } else {
+        nonStatusAssertions.push(
+          `assert.equal(${headersReference}.get(${sourceCode.getText(headerName)}), ${sourceCode.getText(headerValue)})`,
+        );
+      }
+    }
+  }
+  return {
+    statusAssertion,
+    nonStatusAssertions,
+  };
+}
+
+function getResponseHeadersAccesses(
+  responseVariables: Scope.Variable[],
+  scopeManager: Scope.ScopeManager,
+  sourceCode: SourceCode,
+) {
+  const responseHeadersAccesses: MemberExpression[] = [];
+  for (const responseVariable of responseVariables) {
+    for (const responseReference of responseVariable.references) {
+      const responseAccess = getParent(responseReference.identifier);
+      if (!responseAccess || responseAccess.type !== 'MemberExpression') {
+        continue;
+      }
+
+      const responseAccessParent = getParent(responseAccess);
+      if (!responseAccessParent) {
+        continue;
+      }
+
+      if (
+        responseAccessParent.type === 'CallExpression' &&
+        responseAccessParent.arguments[0]?.type === 'ArrowFunctionExpression'
+      ) {
+        // map-like operation against responses, e.g. responses.map((response) => response.headers.etag)
+        responseHeadersAccesses.push(
+          ...getResponseHeadersAccesses(
+            scopeManager.getDeclaredVariables(responseAccessParent.arguments[0]),
+            scopeManager,
+            sourceCode,
+          ),
+        );
+        continue;
+      }
+
+      if (
+        responseAccess.computed &&
+        responseAccess.property.type === 'Literal' &&
+        responseAccessParent.type === 'MemberExpression'
+      ) {
+        // header access through indexed responses array, e.g. responses[0].headers, responses[1].get(...), etc.
+        responseHeadersAccesses.push(responseAccessParent);
+      } else {
+        responseHeadersAccesses.push(responseAccess);
+      }
+    }
+  }
+  return responseHeadersAccesses;
+}
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Prefer native fetch API over customized fixture API.',
+      url: getDocumentationUrl(ruleId),
+    },
+    messages: {
+      preferNativeFetch: 'Prefer native fetch API over customized fixture API.',
+      shouldUseHeaderGetter: 'Getter should be used to access response headers.',
+      unknownError: 'Unknown error occurred in file "{{fileName}}": {{ error }}.',
+    },
+    fixable: 'code',
+    schema: [],
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode;
+    const scopeManager = sourceCode.scopeManager;
+
+    return {
+      'CallExpression[callee.object.object.name="fixture"][callee.object.property.name="api"]': (
+        fixtureCall: CallExpression,
+        // eslint-disable-next-line sonarjs/cognitive-complexity
+      ) => {
+        try {
+          if (!hasAssertions(fixtureCall)) {
+            // skip if there are no assertions, let "no-fixture" rule to handle the conversion
+            return;
+          }
+
+          if (!(isUsedInArrayOrAsArgument(fixtureCall) || getEnclosingFunction(fixtureCall)?.async === false)) {
+            return;
+          }
+
+          assert.ok(fixtureCall.type === 'CallExpression');
+          const fixtureFunction = fixtureCall.callee; // e.g. fixture.api.get
+          assert.ok(fixtureFunction.type === 'MemberExpression');
+          const indentation = getIndentation(fixtureCall, sourceCode);
+
+          const [urlArgumentNode] = fixtureCall.arguments; // e.g. `/sample-service/v1/ping`
+          assert.ok(urlArgumentNode !== undefined);
+
+          const fixtureCallInformation = {} as FixtureCallInformation;
+          analyzeFixtureCall(fixtureCall, fixtureCallInformation, sourceCode);
+
+          // convert url from `/sample-service/v1/ping` to `${BASE_PATH}/ping`
+          const originalUrlArgumentText = sourceCode.getText(urlArgumentNode);
+          const fetchUrlArgumentText = replaceEndpointUrlPrefixWithBasePath(originalUrlArgumentText);
+
+          // fetch request argument
+          const methodNode = fixtureFunction.property; // get/put/etc.
+          assert.ok(methodNode.type === 'Identifier');
+          const fetchRequestArgumentLines = [
+            '{',
+            `  method: '${methodNode.name.toUpperCase()}',`,
+            ...(fixtureCallInformation.requestBody
+              ? [`  body: JSON.stringify(${sourceCode.getText(fixtureCallInformation.requestBody)}),`]
+              : []),
+            ...(fixtureCallInformation.requestHeaders
+              ? [
+                  `  headers: {`,
+                  ...fixtureCallInformation.requestHeaders.map(
+                    ({ name, value }) =>
+                      // eslint-disable-next-line @typescript-eslint/restrict-template-expressions, no-nested-ternary, sonarjs/no-nested-template-literals
+                      `    ${name.type === 'Literal' ? (isValidPropertyName(name.value) ? name.value : `'${name.value}'`) : `[${sourceCode.getText(name)}]`}: ${sourceCode.getText(value)},`,
+                  ),
+                  `  },`,
+                ]
+              : []),
+            '}',
+          ].join(`\n${indentation}`);
+
+          const responseVariableNameToUse = 'res';
+          const { statusAssertion, nonStatusAssertions } = createResponseAssertions(
+            fixtureCallInformation,
+            sourceCode,
+            responseVariableNameToUse,
+          );
+
+          // add variable declaration if needed
+          const disableLintComment = '// eslint-disable-next-line @checkdigit/no-promise-instance-method';
+          const fetchCallText = `fetch(${fetchUrlArgumentText}, ${fetchRequestArgumentLines})`;
+          const appendingAssignmentAndAssertionText = [
+            ...(statusAssertion !== undefined ? [statusAssertion] : []),
+            ...nonStatusAssertions,
+          ].join(`;\n${indentation}`);
+          const replacementText = fixtureCallInformation.assertions
+            ? [
+                disableLintComment,
+                `${fetchCallText}.then((${responseVariableNameToUse}) => {`,
+                appendingAssignmentAndAssertionText === '' ? '' : `  ${appendingAssignmentAndAssertionText};`,
+                `  return ${responseVariableNameToUse};`,
+                `})`,
+              ].join(`\n${indentation}`)
+            : fetchCallText;
+
+          context.report({
+            node: fixtureCall,
+            messageId: 'preferNativeFetch',
+            fix(fixer) {
+              return fixer.replaceText(fixtureCallInformation.fixtureNode, replacementText);
+            },
+          });
+
+          const responsesVariable = getEnclosingStatement(fixtureCallInformation.fixtureNode);
+          if (!responsesVariable) {
+            return;
+          }
+
+          const responseVariableReferences = scopeManager.getDeclaredVariables(responsesVariable);
+          const responseHeadersAccesses = getResponseHeadersAccesses(
+            responseVariableReferences,
+            scopeManager,
+            sourceCode,
+          );
+          for (const responseHeadersAccess of responseHeadersAccesses) {
+            if (isInvalidResponseHeadersAccess(responseHeadersAccess)) {
+              const headerAccess = getParent(responseHeadersAccess);
+              if (headerAccess?.type === 'MemberExpression') {
+                const headerNameNode = headerAccess.property;
+                const headerName = headerAccess.computed
+                  ? sourceCode.getText(headerNameNode)
+                  : `'${sourceCode.getText(headerNameNode)}'`;
+                const headerAccessReplacementText = `${sourceCode.getText(headerAccess.object)}.get(${headerName})`;
+
+                context.report({
+                  node: headerAccess,
+                  messageId: 'shouldUseHeaderGetter',
+                  fix(fixer) {
+                    return fixer.replaceText(headerAccess, headerAccessReplacementText);
+                  },
+                });
+              } else if (
+                headerAccess?.type === 'CallExpression' &&
+                responseHeadersAccess.property.type === 'Identifier' &&
+                responseHeadersAccess.property.name === 'get'
+              ) {
+                const headerAccessReplacementText = `${sourceCode.getText(responseHeadersAccess.object)}.headers.get(${sourceCode.getText(headerAccess.arguments[0])})`;
+
+                context.report({
+                  node: headerAccess,
+                  messageId: 'shouldUseHeaderGetter',
+                  fix(fixer) {
+                    return fixer.replaceText(headerAccess, headerAccessReplacementText);
+                  },
+                });
+              }
+            }
+          }
+        } catch (error) {
+          // eslint-disable-next-line no-console
+          console.error(`Failed to apply ${ruleId} rule for file "${context.filename}":`, error);
+          context.report({
+            node: fixtureCall,
+            messageId: 'unknownError',
+            data: {
+              fileName: context.filename,
+              error: error instanceof Error ? error.toString() : JSON.stringify(error),
+            },
+          });
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/src/agent/fetch.ts

@@ -0,0 +1,53 @@
+// agent/fetch.ts
+
+import type { Node } from 'estree';
+
+import { getParent, isBlockStatement } from '../library/tree';
+
+export function getResponseBodyRetrievalText(responseVariableName: string) {
+  return `await ${responseVariableName}.json()`;
+}
+
+export function isInvalidResponseHeadersAccess(responseHeadersAccess: Node): boolean {
+  const responseHeaderAccessParent = getParent(responseHeadersAccess);
+  if (responseHeaderAccessParent?.type === 'VariableDeclarator') {
+    return false;
+  }
+
+  if (
+    responseHeaderAccessParent?.type === 'CallExpression' &&
+    responseHeaderAccessParent.callee.type === 'MemberExpression' &&
+    responseHeaderAccessParent.callee.property.type === 'Identifier' &&
+    responseHeaderAccessParent.callee.property.name === 'get'
+  ) {
+    return true;
+  }
+
+  return !(
+    responseHeaderAccessParent?.type === 'MemberExpression' &&
+    responseHeaderAccessParent.property.type === 'Identifier' &&
+    responseHeaderAccessParent.property.name === 'get'
+  );
+}
+
+export function hasAssertions(fixtureCall: Node): boolean {
+  if (isBlockStatement(fixtureCall)) {
+    return false;
+  }
+
+  const parent = getParent(fixtureCall);
+  if (!parent) {
+    return false;
+  }
+
+  if (
+    parent.type === 'MemberExpression' &&
+    parent.property.type === 'Identifier' &&
+    parent.property.name === 'expect' &&
+    getParent(parent)?.type === 'CallExpression'
+  ) {
+    return true;
+  }
+
+  return hasAssertions(parent);
+}

package/src/agent/fix-function-call-arguments.ts

@@ -0,0 +1,184 @@
+// agent/fix-function-call-arguments.ts
+
+/*
+ * Copyright (c) 2021-2024 Check Digit, LLC
+ *
+ * This code is licensed under the MIT license (see LICENSE.txt for details).
+ */
+
+import { strict as assert } from 'node:assert';
+import { ESLintUtils, TSESTree } from '@typescript-eslint/utils';
+import debug from 'debug';
+import getDocumentationUrl from '../get-documentation-url';
+
+export const ruleId = 'fix-function-call-arguments';
+
+export interface FixFunctionCallArgumentsRuleOptions {
+  typesToCheck: string[];
+}
+const DEFAULT_OPTIONS = {
+  typesToCheck: [
+    'Configuration<ResolvedServices>',
+    'Fixture<ResolvedServices>',
+    'InboundContext',
+    '{ get: () => string; }',
+  ],
+};
+
+const createRule = ESLintUtils.RuleCreator((name) => getDocumentationUrl(name));
+const log = debug('eslint-plugin:fix-function-call-arguments');
+
+const rule: ESLintUtils.RuleModule<
+  'removeIncompatibleFunctionArguments' | 'unknownError',
+  [FixFunctionCallArgumentsRuleOptions]
+> = createRule({
+  name: ruleId,
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Remove incompatible function arguments.',
+    },
+    messages: {
+      removeIncompatibleFunctionArguments: 'Removing incompatible function arguments.',
+      unknownError: 'Unknown error occurred in file "{{fileName}}": {{ error }}.',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          typesToCheck: {
+            description: 'Text representation of the types of which the function call parameters will be examine',
+            type: 'array',
+            items: {
+              type: 'string',
+            },
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [DEFAULT_OPTIONS],
+  create(context) {
+    const { typesToCheck } = context.options[0];
+    const parserServices = ESLintUtils.getParserServices(context);
+    const typeChecker = parserServices.program.getTypeChecker();
+    const sourceCode = context.sourceCode;
+
+    return {
+      CallExpression(callExpression) {
+        // ignore calls like `foo.bar()` which are likely to be 3rd party module calls
+        // we only focus on calls against local functions or functions imported from the same module
+        if (callExpression.callee.type === TSESTree.AST_NODE_TYPES.MemberExpression) {
+          return;
+        }
+
+        log('===== file name:', context.filename);
+        log('callExpression:', sourceCode.getText(callExpression));
+        try {
+          const calleeTsNode = parserServices.esTreeNodeToTSNodeMap.get(callExpression.callee);
+          const calleeType = typeChecker.getTypeAtLocation(calleeTsNode);
+
+          const signatures = calleeType.getCallSignatures();
+          if (signatures.length > 1) {
+            // ignore complex signatures with overloads
+            return;
+          }
+
+          const signature = signatures[0];
+          assert.ok(signature, 'Signature not found.');
+          if (signature.typeParameters !== undefined && signature.typeParameters.length > 0) {
+            // ignore complex signatures with type parameters
+            return;
+          }
+
+          log('signature:', signature.getDeclaration().getText());
+          const expectedParameters = signature.getParameters();
+          log(
+            'expected parameters:',
+            expectedParameters.map((expectedParameter) =>
+              typeChecker.typeToString(typeChecker.getTypeOfSymbol(expectedParameter)),
+            ),
+          );
+          const expectedParametersCount = expectedParameters.length;
+          const actualParameters = callExpression.arguments;
+          const actualParametersCount = actualParameters.length;
+          if (actualParametersCount === 0 || actualParametersCount === expectedParametersCount) {
+            return;
+          }
+
+          const parametersToKeep: TSESTree.CallExpressionArgument[] = [];
+          let expectedParameterIndex = 0;
+          for (const [actualParameterIndex, actualParameter] of actualParameters.entries()) {
+            if (expectedParameterIndex >= expectedParametersCount) {
+              break;
+            }
+
+            const expectedParameter = expectedParameters[expectedParameterIndex];
+            assert.ok(expectedParameter, 'Expected parameter not found.');
+
+            const expectedType = typeChecker.getTypeOfSymbol(expectedParameter);
+            const actualType = typeChecker.getTypeAtLocation(parserServices.esTreeNodeToTSNodeMap.get(actualParameter));
+            const actualTypeString = typeChecker.typeToString(actualType);
+            log(
+              'expected type: #',
+              expectedParameterIndex,
+              expectedParameter.escapedName,
+              typeChecker.typeToString(expectedType),
+            );
+            log('actual type: #', actualParameterIndex, sourceCode.getText(actualParameter), actualTypeString);
+
+            if (!typesToCheck.includes(actualTypeString) && !actualTypeString.endsWith('RequestType')) {
+              // skip the parameter type checking if it's not in the candidate types
+              parametersToKeep.push(actualParameter);
+              log('skipped');
+            } else if (typeChecker.isTypeAssignableTo(actualType, expectedType)) {
+              parametersToKeep.push(actualParameter);
+              log('matched');
+              expectedParameterIndex++;
+            } else {
+              log('not matched');
+            }
+          }
+
+          if (parametersToKeep.length === actualParametersCount) {
+            return;
+          }
+
+          const firstParameter = actualParameters[0];
+          const lastParameter = actualParameters.at(-1);
+          assert.ok(firstParameter !== undefined && lastParameter !== undefined);
+          const tokenAfterParameters = sourceCode.getTokenAfter(lastParameter);
+
+          context.report({
+            node: callExpression,
+            messageId: 'removeIncompatibleFunctionArguments',
+            fix(fixer) {
+              return fixer.replaceTextRange(
+                [
+                  firstParameter.range[0],
+                  tokenAfterParameters?.value === ',' ? tokenAfterParameters.range[1] : lastParameter.range[1],
+                ],
+                parametersToKeep.map((arg) => sourceCode.getText(arg)).join(', '),
+              );
+            },
+          });
+        } catch (error) {
+          // eslint-disable-next-line no-console
+          console.error(`Failed to apply ${ruleId} rule for file "${context.filename}":`, error);
+          context.report({
+            node: callExpression,
+            messageId: 'unknownError',
+            data: {
+              fileName: context.filename,
+              error: error instanceof Error ? error.toString() : JSON.stringify(error),
+            },
+          });
+        }
+      },
+    };
+  },
+});
+
+export default rule;