@depup/eslint-plugin-jsdoc 62.8.0-depup.0

package/src/rules/checkParamNames.js

@@ -0,0 +1,541 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+/**
+ * @param {string} targetTagName
+ * @param {boolean} allowExtraTrailingParamDocs
+ * @param {boolean} checkDestructured
+ * @param {boolean} checkRestProperty
+ * @param {RegExp} checkTypesRegex
+ * @param {boolean} disableExtraPropertyReporting
+ * @param {boolean} disableMissingParamChecks
+ * @param {boolean} enableFixer
+ * @param {import('../jsdocUtils.js').ParamNameInfo[]} functionParameterNames
+ * @param {import('comment-parser').Block} jsdoc
+ * @param {import('../iterateJsdoc.js').Utils} utils
+ * @param {import('../iterateJsdoc.js').Report} report
+ * @returns {boolean}
+ */
+const validateParameterNames = (
+  targetTagName,
+  allowExtraTrailingParamDocs,
+  checkDestructured,
+  checkRestProperty,
+  checkTypesRegex,
+  disableExtraPropertyReporting,
+  disableMissingParamChecks,
+  enableFixer,
+  functionParameterNames, jsdoc, utils, report,
+) => {
+  const paramTags = Object.entries(jsdoc.tags).filter(([
+    , tag,
+  ]) => {
+    return tag.tag === targetTagName;
+  });
+  const paramTagsNonNested = paramTags.filter(([
+    , tag,
+  ]) => {
+    return !tag.name.includes('.');
+  });
+
+  let dotted = 0;
+  let thisOffset = 0;
+
+  return paramTags.some(([
+    , tag,
+  // eslint-disable-next-line complexity
+  ], index) => {
+    /** @type {import('../iterateJsdoc.js').Integer} */
+    let tagsIndex;
+    const dupeTagInfo = paramTags.find(([
+      tgsIndex,
+      tg,
+    ], idx) => {
+      tagsIndex = Number(tgsIndex);
+
+      return tg.name === tag.name && idx !== index;
+    });
+    if (dupeTagInfo) {
+      utils.reportJSDoc(`Duplicate @${targetTagName} "${tag.name}"`, dupeTagInfo[1], enableFixer ? () => {
+        utils.removeTag(tagsIndex);
+      } : null);
+
+      return true;
+    }
+
+    if (tag.name.includes('.')) {
+      dotted++;
+
+      return false;
+    }
+
+    let functionParameterName = functionParameterNames[index - dotted + thisOffset];
+    if (functionParameterName === 'this' && tag.name.trim() !== 'this') {
+      ++thisOffset;
+      functionParameterName = functionParameterNames[index - dotted + thisOffset];
+    }
+
+    if (!functionParameterName) {
+      if (allowExtraTrailingParamDocs) {
+        return false;
+      }
+
+      report(
+        `@${targetTagName} "${tag.name}" does not match an existing function parameter.`,
+        null,
+        tag,
+      );
+
+      return true;
+    }
+
+    if (
+      typeof functionParameterName === 'object' &&
+        'name' in functionParameterName &&
+        Array.isArray(functionParameterName.name)
+    ) {
+      const actualName = tag.name.trim();
+      const expectedName = functionParameterName.name[index];
+      if (actualName === expectedName) {
+        thisOffset--;
+        return false;
+      }
+
+      report(
+        `Expected @${targetTagName} name to be "${expectedName}". Got "${actualName}".`,
+        null,
+        tag,
+      );
+      return true;
+    }
+
+    if (Array.isArray(functionParameterName)) {
+      if (!checkDestructured) {
+        return false;
+      }
+
+      if (tag.type && tag.type.search(checkTypesRegex) === -1) {
+        return false;
+      }
+
+      const [
+        parameterName,
+        {
+          annotationParamName,
+          hasPropertyRest,
+          names: properties,
+          rests,
+        },
+      ] =
+        /**
+         * @type {[string | undefined, import('../jsdocUtils.js').FlattendRootInfo & {
+         *   annotationParamName?: string | undefined;
+          }]} */ (functionParameterName);
+      if (annotationParamName !== undefined) {
+        const name = tag.name.trim();
+        if (name !== annotationParamName) {
+          report(`@${targetTagName} "${name}" does not match parameter name "${annotationParamName}"`, null, tag);
+        }
+      }
+
+      const tagName = parameterName === undefined ? tag.name.trim() : parameterName;
+      const expectedNames = properties.map((name) => {
+        return `${tagName}.${name}`;
+      });
+      const actualNames = paramTags.map(([
+        , paramTag,
+      ]) => {
+        return paramTag.name.trim();
+      });
+      const actualTypes = paramTags.map(([
+        , paramTag,
+      ]) => {
+        return paramTag.type;
+      });
+
+      const missingProperties = [];
+
+      /** @type {string[]} */
+      const notCheckingNames = [];
+
+      for (const [
+        idx,
+        name,
+      ] of expectedNames.entries()) {
+        if (notCheckingNames.some((notCheckingName) => {
+          return name.startsWith(notCheckingName);
+        })) {
+          continue;
+        }
+
+        const actualNameIdx = actualNames.findIndex((actualName) => {
+          return utils.comparePaths(name)(actualName);
+        });
+        if (actualNameIdx === -1) {
+          if (!checkRestProperty && rests[idx]) {
+            continue;
+          }
+
+          const missingIndex = actualNames.findIndex((actualName) => {
+            return utils.pathDoesNotBeginWith(name, actualName);
+          });
+          const line = tag.source[0].number - 1 + (missingIndex > -1 ? missingIndex : actualNames.length);
+          missingProperties.push({
+            name,
+            tagPlacement: {
+              line: line === 0 ? 1 : line,
+            },
+          });
+        } else if (actualTypes[actualNameIdx].search(checkTypesRegex) === -1 && actualTypes[actualNameIdx] !== '') {
+          notCheckingNames.push(name);
+        }
+      }
+
+      const hasMissing = missingProperties.length;
+      if (hasMissing) {
+        for (const {
+          name: missingProperty,
+          tagPlacement,
+        } of missingProperties) {
+          report(`Missing @${targetTagName} "${missingProperty}"`, null, tagPlacement);
+        }
+      }
+
+      if (!hasPropertyRest || checkRestProperty) {
+        /** @type {[string, import('comment-parser').Spec][]} */
+        const extraProperties = [];
+        for (const [
+          idx,
+          name,
+        ] of actualNames.entries()) {
+          const match = name.startsWith(tag.name.trim() + '.');
+          if (
+            match && !expectedNames.some(
+              utils.comparePaths(name),
+            ) && !utils.comparePaths(name)(tag.name) &&
+            (!disableExtraPropertyReporting || properties.some((prop) => {
+              return prop.split('.').length >= name.split('.').length - 1;
+            }))
+          ) {
+            extraProperties.push([
+              name, paramTags[idx][1],
+            ]);
+          }
+        }
+
+        if (extraProperties.length) {
+          for (const [
+            extraProperty,
+            tg,
+          ] of extraProperties) {
+            report(`@${targetTagName} "${extraProperty}" does not exist on ${tag.name}`, null, tg);
+          }
+
+          return true;
+        }
+      }
+
+      return hasMissing;
+    }
+
+    let funcParamName;
+    if (typeof functionParameterName === 'object') {
+      const {
+        name,
+      } = functionParameterName;
+      funcParamName = name;
+    } else {
+      funcParamName = functionParameterName;
+    }
+
+    if (funcParamName !== tag.name.trim()) {
+      // Todo: Improve for array or object child items
+      const actualNames = paramTagsNonNested.map(([
+        , {
+          name,
+        },
+      ]) => {
+        return name.trim();
+      });
+
+      const expectedNames = functionParameterNames.map((item, idx) => {
+        if (/**
+             * @type {[string|undefined, (import('../jsdocUtils.js').FlattendRootInfo & {
+             *   annotationParamName?: string,
+              })]} */ (item)?.[1]?.names) {
+          return actualNames[idx];
+        }
+
+        return item;
+      }).filter((item) => {
+        return item !== 'this';
+      });
+
+      // When disableMissingParamChecks is true tag names can be omitted.
+      // Report when the tag names do not match the expected names or they are used out of order.
+      if (disableMissingParamChecks) {
+        const usedExpectedNames = expectedNames.map((a) => {
+          return a?.toString();
+        }).filter((expectedName) => {
+          return expectedName && actualNames.includes(expectedName);
+        });
+        const usedInOrder = actualNames.every((actualName, idx) => {
+          return actualName === usedExpectedNames[idx];
+        });
+        if (usedInOrder) {
+          return false;
+        }
+      }
+
+      report(
+        `Expected @${targetTagName} names to be "${
+          expectedNames.map((expectedName) => {
+            return typeof expectedName === 'object' &&
+              'name' in expectedName &&
+              expectedName.restElement ?
+              '...' + expectedName.name :
+              expectedName;
+          }).join(', ')
+        }". Got "${actualNames.join(', ')}".`,
+        null,
+        tag,
+      );
+
+      return true;
+    }
+
+    return false;
+  });
+};
+
+/**
+ * @param {string} targetTagName
+ * @param {boolean} _allowExtraTrailingParamDocs
+ * @param {{
+ *   name: string,
+ *   idx: import('../iterateJsdoc.js').Integer
+ * }[]} jsdocParameterNames
+ * @param {import('comment-parser').Block} jsdoc
+ * @param {import('../iterateJsdoc.js').Report} report
+ * @returns {boolean}
+ */
+const validateParameterNamesDeep = (
+  targetTagName, _allowExtraTrailingParamDocs,
+  jsdocParameterNames, jsdoc, report,
+) => {
+  /** @type {string} */
+  let lastRealParameter;
+
+  return jsdocParameterNames.some(({
+    idx,
+    name: jsdocParameterName,
+  }) => {
+    const isPropertyPath = jsdocParameterName.includes('.');
+
+    if (isPropertyPath) {
+      if (!lastRealParameter) {
+        report(`@${targetTagName} path declaration ("${jsdocParameterName}") appears before any real parameter.`, null, jsdoc.tags[idx]);
+
+        return true;
+      }
+
+      let pathRootNodeName = jsdocParameterName.slice(0, jsdocParameterName.indexOf('.'));
+
+      if (pathRootNodeName.endsWith('[]')) {
+        pathRootNodeName = pathRootNodeName.slice(0, -2);
+      }
+
+      if (pathRootNodeName !== lastRealParameter) {
+        report(
+          `@${targetTagName} path declaration ("${jsdocParameterName}") root node name ("${pathRootNodeName}") ` +
+          `does not match previous real parameter name ("${lastRealParameter}").`,
+          null,
+          jsdoc.tags[idx],
+        );
+
+        return true;
+      }
+    } else {
+      lastRealParameter = jsdocParameterName;
+    }
+
+    return false;
+  });
+};
+
+const allowedNodes = [
+  'ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'TSDeclareFunction',
+  // Add this to above defaults
+  'TSMethodSignature', 'TSPropertySignature',
+];
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  node,
+  report,
+  utils,
+}) => {
+  const {
+    allowExtraTrailingParamDocs,
+    checkDestructured = true,
+    checkRestProperty = false,
+    checkTypesPattern = '/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/',
+    disableExtraPropertyReporting = false,
+    disableMissingParamChecks = false,
+    enableFixer = false,
+    useDefaultObjectProperties = false,
+  } = context.options[0] || {};
+
+  const nde = /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (node);
+
+  // Although we might just remove global settings contexts from applying to
+  //   this rule (as they can cause problems with `getFunctionParameterNames`
+  //   checks if they are not functions but say variables), the user may
+  //   instead wish to narrow contexts in those settings, so this check
+  //   is still useful
+  if (!allowedNodes.includes(nde.type) ||
+    nde.type === 'TSPropertySignature' &&
+      (/** @type {import('@typescript-eslint/types').TSESTree.TSPropertySignature} */ (
+        nde
+      )?.typeAnnotation?.typeAnnotation?.type !== 'TSFunctionType')) {
+    return;
+  }
+
+  const checkTypesRegex = utils.getRegexFromString(checkTypesPattern);
+
+  const jsdocParameterNamesDeep = utils.getJsdocTagsDeep('param');
+  if (!jsdocParameterNamesDeep || !jsdocParameterNamesDeep.length) {
+    return;
+  }
+
+  const functionParameterNames = utils.getFunctionParameterNames(useDefaultObjectProperties);
+
+  const targetTagName = /** @type {string} */ (utils.getPreferredTagName({
+    tagName: 'param',
+  }));
+  const isError = validateParameterNames(
+    targetTagName,
+    allowExtraTrailingParamDocs,
+    checkDestructured,
+    checkRestProperty,
+    checkTypesRegex,
+    disableExtraPropertyReporting,
+    disableMissingParamChecks,
+    enableFixer,
+    functionParameterNames,
+    jsdoc,
+    utils,
+    report,
+  );
+
+  if (isError || !checkDestructured) {
+    return;
+  }
+
+  validateParameterNamesDeep(
+    targetTagName, allowExtraTrailingParamDocs, jsdocParameterNamesDeep, jsdoc, report,
+  );
+}, {
+  contextDefaults: allowedNodes,
+  meta: {
+    docs: {
+      description: 'Checks for dupe `@param` names, that nested param names have roots, and that parameter names in function declarations match JSDoc param names.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-param-names.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          allowExtraTrailingParamDocs: {
+            description: `If set to \`true\`, this option will allow extra \`@param\` definitions (e.g.,
+representing future expected or virtual params) to be present without needing
+their presence within the function signature. Other inconsistencies between
+\`@param\`'s and present function parameters will still be reported.`,
+            type: 'boolean',
+          },
+          checkDestructured: {
+            description: 'Whether to check destructured properties. Defaults to `true`.',
+            type: 'boolean',
+          },
+          checkRestProperty: {
+            description: `If set to \`true\`, will require that rest properties are documented and
+that any extraneous properties (which may have been within the rest property)
+are documented. Defaults to \`false\`.`,
+            type: 'boolean',
+          },
+          checkTypesPattern: {
+            description: `Defines a regular expression pattern to indicate which types should be
+checked for destructured content (and that those not matched should not
+be checked).
+
+When one specifies a type, unless it is of a generic type, like \`object\`
+or \`array\`, it may be considered unnecessary to have that object's
+destructured components required, especially where generated docs will
+link back to the specified type. For example:
+
+\`\`\`js
+/**
+ * @param {SVGRect} bbox - a SVGRect
+ */
+export const bboxToObj = function ({x, y, width, height}) {
+  return {x, y, width, height};
+};
+\`\`\`
+
+By default \`checkTypesPattern\` is set to
+\`/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/v\`,
+meaning that destructuring will be required only if the type of the \`@param\`
+(the text between curly brackets) is a match for "Object" or "Array" (with or
+without initial caps), "PlainObject", or "GenericObject", "GenericArray" (or
+if no type is present). So in the above example, the lack of a match will
+mean that no complaint will be given about the undocumented destructured
+parameters.
+
+Note that the \`/\` delimiters are optional, but necessary to add flags.
+
+Defaults to using (only) the \`v\` flag, so to add your own flags, encapsulate
+your expression as a string, but like a literal, e.g., \`/^object$/vi\`.
+
+You could set this regular expression to a more expansive list, or you
+could restrict it such that even types matching those strings would not
+need destructuring.`,
+            type: 'string',
+          },
+          disableExtraPropertyReporting: {
+            description: `Whether to check for extra destructured properties. Defaults to \`false\`. Change
+to \`true\` if you want to be able to document properties which are not actually
+destructured. Keep as \`false\` if you expect properties to be documented in
+their own types. Note that extra properties will always be reported if another
+item at the same level is destructured as destructuring will prevent other
+access and this option is only intended to permit documenting extra properties
+that are available and actually used in the function.`,
+            type: 'boolean',
+          },
+          disableMissingParamChecks: {
+            description: 'Whether to avoid checks for missing `@param` definitions. Defaults to `false`. Change to `true` if you want to be able to omit properties.',
+            type: 'boolean',
+          },
+          enableFixer: {
+            description: `Set to \`true\` to auto-remove \`@param\` duplicates (based on identical
+names).
+
+Note that this option will remove duplicates of the same name even if
+the definitions do not match in other ways (e.g., the second param will
+be removed even if it has a different type or description).`,
+            type: 'boolean',
+          },
+          useDefaultObjectProperties: {
+            description: `Set to \`true\` if you wish to avoid reporting of child property documentation
+where instead of destructuring, a whole plain object is supplied as default
+value but you wish its keys to be considered as signalling that the properties
+are present and can therefore be documented. Defaults to \`false\`.`,
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/checkPropertyNames.js

@@ -0,0 +1,174 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+/**
+ * @param {string} targetTagName
+ * @param {boolean} enableFixer
+ * @param {import('comment-parser').Block} jsdoc
+ * @param {import('../iterateJsdoc.js').Utils} utils
+ * @returns {boolean}
+ */
+const validatePropertyNames = (
+  targetTagName,
+  enableFixer,
+  jsdoc, utils,
+) => {
+  const jsdocTypedefs = utils.getJsdocTagsDeep('typedef');
+  let propertyTagGroups;
+  if (jsdocTypedefs && jsdocTypedefs.length > 1) {
+    propertyTagGroups = jsdocTypedefs.map(({
+      idx,
+    }, index) => {
+      return Object.entries(jsdoc.tags).slice(idx, jsdocTypedefs[index + 1]?.idx);
+    });
+  } else {
+    propertyTagGroups = [
+      Object.entries(jsdoc.tags),
+    ];
+  }
+
+  return propertyTagGroups.some((propertyTagGroup) => {
+    const propertyTags = propertyTagGroup.filter(([
+      , tag,
+    ]) => {
+      return tag.tag === targetTagName;
+    });
+
+    return propertyTags.some(([
+      , tag,
+    ], index) => {
+      /** @type {import('../iterateJsdoc.js').Integer} */
+      let tagsIndex;
+      const dupeTagInfo = propertyTags.find(([
+        tgsIndex,
+        tg,
+      ], idx) => {
+        tagsIndex = Number(tgsIndex);
+
+        return tg.name === tag.name && idx !== index;
+      });
+      if (dupeTagInfo) {
+        utils.reportJSDoc(`Duplicate @${targetTagName} "${tag.name}"`, dupeTagInfo[1], enableFixer ? () => {
+          utils.removeTag(tagsIndex);
+        } : null);
+
+        return true;
+      }
+
+      return false;
+    });
+  });
+};
+
+/**
+ * @param {string} targetTagName
+ * @param {{
+ *   idx: number;
+ *   name: string;
+ *   type: string;
+ * }[]} jsdocPropertyNames
+ * @param {import('comment-parser').Block} jsdoc
+ * @param {import('../iterateJsdoc.js').Report} report
+ */
+const validatePropertyNamesDeep = (
+  targetTagName,
+  jsdocPropertyNames, jsdoc, report,
+) => {
+  /** @type {string} */
+  let lastRealProperty;
+
+  return jsdocPropertyNames.some(({
+    idx,
+    name: jsdocPropertyName,
+  }) => {
+    const isPropertyPath = jsdocPropertyName.includes('.');
+
+    if (isPropertyPath) {
+      if (!lastRealProperty) {
+        report(`@${targetTagName} path declaration ("${jsdocPropertyName}") appears before any real property.`, null, jsdoc.tags[idx]);
+
+        return true;
+      }
+
+      let pathRootNodeName = jsdocPropertyName.slice(0, jsdocPropertyName.indexOf('.'));
+
+      if (pathRootNodeName.endsWith('[]')) {
+        pathRootNodeName = pathRootNodeName.slice(0, -2);
+      }
+
+      if (pathRootNodeName !== lastRealProperty) {
+        report(
+          `@${targetTagName} path declaration ("${jsdocPropertyName}") root node name ("${pathRootNodeName}") ` +
+          `does not match previous real property name ("${lastRealProperty}").`,
+          null,
+          jsdoc.tags[idx],
+        );
+
+        return true;
+      }
+    } else {
+      lastRealProperty = jsdocPropertyName;
+    }
+
+    return false;
+  });
+};
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  report,
+  utils,
+}) => {
+  const {
+    enableFixer = false,
+  } = context.options[0] || {};
+  const jsdocPropertyNamesDeep = utils.getJsdocTagsDeep('property');
+  if (!jsdocPropertyNamesDeep || !jsdocPropertyNamesDeep.length) {
+    return;
+  }
+
+  const targetTagName = /** @type {string} */ (utils.getPreferredTagName({
+    tagName: 'property',
+  }));
+  const isError = validatePropertyNames(
+    targetTagName,
+    enableFixer,
+    jsdoc,
+    utils,
+  );
+
+  if (isError) {
+    return;
+  }
+
+  validatePropertyNamesDeep(
+    targetTagName, jsdocPropertyNamesDeep, jsdoc, report,
+  );
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Ensures that property names in JSDoc are not duplicated on the same block and that nested properties have defined roots.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-property-names.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          enableFixer: {
+            description: `Set to \`true\` to auto-remove \`@property\` duplicates (based on
+identical names).
+
+Note that this option will remove duplicates of the same name even if
+the definitions do not match in other ways (e.g., the second property will
+be removed even if it has a different type or description).`,
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});