eslint-plugin-jsdoc 52.0.1 → 52.0.3

package/src/rules/validTypes.js

@@ -1,401 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-import {
-  parse,
-  traverse,
-  tryParse,
-} from '@es-joy/jsdoccomment';
-
-const inlineTags = new Set([
-  'link', 'linkcode', 'linkplain',
-  'tutorial',
-]);
-
-const jsdocTypePrattKeywords = new Set([
-  'import',
-  'is',
-  'readonly',
-  'typeof',
-]);
-
-const asExpression = /as\s+/v;
-
-const suppressTypes = new Set([
-  // https://github.com/google/closure-compiler/wiki/@suppress-annotations
-  // https://github.com/google/closure-compiler/blob/master/src/com/google/javascript/jscomp/parsing/ParserConfig.properties#L154
-  'accessControls',
-  'checkDebuggerStatement',
-  'checkEs5InheritanceCorrectnessConditions',
-  'checkPrototypalTypes',
-  'checkRegExp',
-  'checkTypes',
-  'checkVars',
-  'closureClassChecks',
-  'closureDepMethodUsageChecks',
-  'const',
-  'constantProperty',
-  'dangerousUnrecognizedTypeError',
-  'deprecated',
-  'duplicate',
-  'es5Strict',
-  'externsValidation',
-  'extraProvide',
-  'extraRequire',
-  'globalThis',
-  'invalidCasts',
-  'lateProvide',
-  'legacyGoogScopeRequire',
-  'lintChecks',
-  'lintVarDeclarations',
-  'messageConventions',
-  'misplacedTypeAnnotation',
-  'missingOverride',
-  'missingPolyfill',
-  'missingProperties',
-  'missingProvide',
-  'missingRequire',
-  'missingReturn',
-  'missingSourcesWarnings',
-  'moduleLoad',
-  'msgDescriptions',
-  'nonStandardJsDocs',
-  'partialAlias',
-  'polymer',
-  'reportUnknownTypes',
-  'strictCheckTypes',
-  'strictMissingProperties',
-  'strictModuleDepCheck',
-  'strictPrimitiveOperators',
-  'suspiciousCode',
-
-  // Not documented in enum
-  'switch',
-  'transitionalSuspiciousCodeWarnings',
-  'undefinedNames',
-  'undefinedVars',
-  'underscore',
-  'unknownDefines',
-  'untranspilableFeatures',
-  'unusedLocalVariables',
-
-  // Not documented?
-  'unusedPrivateMembers',
-  'uselessCode',
-  'useOfGoogProvide',
-  'visibility',
-  'with',
-]);
-
-/**
- * @param {string} path
- * @returns {boolean}
- */
-const tryParsePathIgnoreError = (path) => {
-  try {
-    tryParse(path);
-
-    return true;
-  } catch {
-    // Keep the original error for including the whole type
-  }
-
-  return false;
-};
-
-// eslint-disable-next-line complexity
-export default iterateJsdoc(({
-  context,
-  jsdoc,
-  report,
-  settings,
-  utils,
-}) => {
-  const {
-    allowEmptyNamepaths = false,
-  } = context.options[0] || {};
-  const {
-    mode,
-  } = settings;
-
-  for (const tag of jsdoc.tags) {
-    /**
-     * @param {string} namepath
-     * @param {string} [tagName]
-     * @returns {boolean}
-     */
-    const validNamepathParsing = function (namepath, tagName) {
-      if (
-        tryParsePathIgnoreError(namepath) ||
-        jsdocTypePrattKeywords.has(namepath)
-      ) {
-        return true;
-      }
-
-      let handled = false;
-
-      if (tagName) {
-        switch (tagName) {
-          case 'memberof':
-          case 'memberof!': {
-            const endChar = namepath.slice(-1);
-            if ([
-              '#', '.', '~',
-            ].includes(endChar)) {
-              handled = tryParsePathIgnoreError(namepath.slice(0, -1));
-            }
-
-            break;
-          }
-
-          case 'module': case 'requires': {
-            if (!namepath.startsWith('module:')) {
-              handled = tryParsePathIgnoreError(`module:${namepath}`);
-            }
-
-            break;
-          }
-
-          case 'borrows': {
-            const startChar = namepath.charAt(0);
-            if ([
-              '#', '.', '~',
-            ].includes(startChar)) {
-              handled = tryParsePathIgnoreError(namepath.slice(1));
-            }
-          }
-        }
-      }
-
-      if (!handled) {
-        report(`Syntax error in namepath: ${namepath}`, null, tag);
-
-        return false;
-      }
-
-      return true;
-    };
-
-    /**
-     * @param {string} type
-     * @returns {boolean}
-     */
-    const validTypeParsing = function (type) {
-      let parsedTypes;
-      try {
-        if (mode === 'permissive') {
-          parsedTypes = tryParse(type);
-        } else {
-          parsedTypes = parse(type, mode);
-        }
-      } catch {
-        report(`Syntax error in type: ${type}`, null, tag);
-
-        return false;
-      }
-
-      if (mode === 'closure' || mode === 'typescript') {
-        traverse(parsedTypes, (node) => {
-          const {
-            type: typ,
-          } = node;
-
-          if (
-            (typ === 'JsdocTypeObjectField' || typ === 'JsdocTypeKeyValue') &&
-            node.right?.type === 'JsdocTypeNullable' &&
-            node.right?.meta?.position === 'suffix'
-          ) {
-            report(`Syntax error in type: ${node.right.type}`, null, tag);
-          }
-        });
-      }
-
-      return true;
-    };
-
-    if (tag.problems.length) {
-      const msg = tag.problems.reduce((str, {
-        message,
-      }) => {
-        return str + '; ' + message;
-      }, '').slice(2);
-      report(`Invalid name: ${msg}`, null, tag);
-      continue;
-    }
-
-    if (tag.tag === 'import') {
-      // A named import will look like a type, but not be valid; we also don't
-      //  need to check the name/namepath
-      continue;
-    }
-
-    if (tag.tag === 'borrows') {
-      const thisNamepath = /** @type {string} */ (
-        utils.getTagDescription(tag)
-      ).replace(asExpression, '')
-        .trim();
-
-      if (!asExpression.test(/** @type {string} */ (
-        utils.getTagDescription(tag)
-      )) || !thisNamepath) {
-        report(`@borrows must have an "as" expression. Found "${utils.getTagDescription(tag)}"`, null, tag);
-
-        continue;
-      }
-
-      if (validNamepathParsing(thisNamepath, 'borrows')) {
-        const thatNamepath = tag.name;
-
-        validNamepathParsing(thatNamepath);
-      }
-
-      continue;
-    }
-
-    if (tag.tag === 'suppress' && mode === 'closure') {
-      let parsedTypes;
-
-      try {
-        parsedTypes = tryParse(tag.type);
-      } catch {
-        // Ignore
-      }
-
-      if (parsedTypes) {
-        traverse(parsedTypes, (node) => {
-          let type;
-          if ('value' in node && typeof node.value === 'string') {
-            type = node.value;
-          }
-
-          if (type !== undefined && !suppressTypes.has(type)) {
-            report(`Syntax error in suppress type: ${type}`, null, tag);
-          }
-        });
-      }
-    }
-
-    const otherModeMaps = /** @type {import('../jsdocUtils.js').ParserMode[]} */ ([
-      'jsdoc', 'typescript', 'closure', 'permissive',
-    ]).filter(
-      (mde) => {
-        return mde !== mode;
-      },
-    ).map((mde) => {
-      return utils.getTagStructureForMode(mde);
-    });
-
-    const tagMightHaveNamePosition = utils.tagMightHaveNamePosition(tag.tag, otherModeMaps);
-    if (tagMightHaveNamePosition !== true && tag.name) {
-      const modeInfo = tagMightHaveNamePosition === false ? '' : ` in "${mode}" mode`;
-      report(`@${tag.tag} should not have a name${modeInfo}.`, null, tag);
-
-      continue;
-    }
-
-    // Documentation like `@returns {@link SomeType}` is technically ambiguous. Specifically it
-    // could either be intepreted as a type `"@link SomeType"` or a description `"{@link SomeType}"`.
-    // However this is a good heuristic.
-    if (tag.type.trim().startsWith('@')) {
-      tag.description = `{${tag.type}} ${tag.description}`;
-      tag.type = '';
-    }
-
-    const mightHaveTypePosition = utils.tagMightHaveTypePosition(tag.tag, otherModeMaps);
-    if (mightHaveTypePosition !== true && tag.type) {
-      const modeInfo = mightHaveTypePosition === false ? '' : ` in "${mode}" mode`;
-      report(`@${tag.tag} should not have a bracketed type${modeInfo}.`, null, tag);
-
-      continue;
-    }
-
-    // REQUIRED NAME
-    const tagMustHaveNamePosition = utils.tagMustHaveNamePosition(tag.tag, otherModeMaps);
-
-    // Don't handle `@param` here though it does require name as handled by
-    //  `require-param-name` (`@property` would similarly seem to require one,
-    //  but is handled by `require-property-name`)
-    if (tagMustHaveNamePosition !== false && !tag.name && !allowEmptyNamepaths && ![
-      'arg', 'argument', 'param',
-      'prop', 'property',
-    ].includes(tag.tag) &&
-      (tag.tag !== 'see' || !utils.getTagDescription(tag).includes('{@link'))
-    ) {
-      const modeInfo = tagMustHaveNamePosition === true ? '' : ` in "${mode}" mode`;
-      report(`Tag @${tag.tag} must have a name/namepath${modeInfo}.`, null, tag);
-
-      continue;
-    }
-
-    // REQUIRED TYPE
-    const mustHaveTypePosition = utils.tagMustHaveTypePosition(tag.tag, otherModeMaps);
-    if (mustHaveTypePosition !== false && !tag.type) {
-      const modeInfo = mustHaveTypePosition === true ? '' : ` in "${mode}" mode`;
-      report(`Tag @${tag.tag} must have a type${modeInfo}.`, null, tag);
-
-      continue;
-    }
-
-    // REQUIRED TYPE OR NAME/NAMEPATH
-    const tagMissingRequiredTypeOrNamepath = utils.tagMissingRequiredTypeOrNamepath(tag, otherModeMaps);
-    if (tagMissingRequiredTypeOrNamepath !== false && !allowEmptyNamepaths) {
-      const modeInfo = tagMissingRequiredTypeOrNamepath === true ? '' : ` in "${mode}" mode`;
-      report(`Tag @${tag.tag} must have either a type or namepath${modeInfo}.`, null, tag);
-
-      continue;
-    }
-
-    // VALID TYPE
-    const hasTypePosition = mightHaveTypePosition === true && Boolean(tag.type);
-    if (hasTypePosition) {
-      validTypeParsing(tag.type);
-    }
-
-    // VALID NAME/NAMEPATH
-    const hasNameOrNamepathPosition = (
-      tagMustHaveNamePosition !== false ||
-      utils.tagMightHaveNamepath(tag.tag)
-    ) && Boolean(tag.name);
-
-    if (hasNameOrNamepathPosition) {
-      if (mode !== 'jsdoc' && tag.tag === 'template') {
-        for (const namepath of utils.parseClosureTemplateTag(tag)) {
-          validNamepathParsing(namepath);
-        }
-      } else {
-        validNamepathParsing(tag.name, tag.tag);
-      }
-    }
-
-    for (const inlineTag of tag.inlineTags) {
-      if (inlineTags.has(inlineTag.tag) && !inlineTag.text && !inlineTag.namepathOrURL) {
-        report(`Inline tag "${inlineTag.tag}" missing content`, null, tag);
-      }
-    }
-  }
-
-  for (const inlineTag of jsdoc.inlineTags) {
-    if (inlineTags.has(inlineTag.tag) && !inlineTag.text && !inlineTag.namepathOrURL) {
-      report(`Inline tag "${inlineTag.tag}" missing content`);
-    }
-  }
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Requires all types to be valid JSDoc or Closure compiler types without syntax errors.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/valid-types.md#repos-sticky-header',
-    },
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          allowEmptyNamepaths: {
-            default: false,
-            type: 'boolean',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});

package/src/tagNames.js

@@ -1,238 +0,0 @@
-/**
- * @typedef {{
- *   [key: string]: string[]
- * }} AliasedTags
- */
-
-/**
- * @type {AliasedTags}
- */
-const jsdocTagsUndocumented = {
-  // Undocumented but present; see
-  // https://github.com/jsdoc/jsdoc/issues/1283#issuecomment-516816802
-  // https://github.com/jsdoc/jsdoc/blob/master/packages/jsdoc/lib/jsdoc/tag/dictionary/definitions.js#L594
-  modifies: [],
-};
-
-/**
- * @type {AliasedTags}
- */
-const jsdocTags = {
-  ...jsdocTagsUndocumented,
-  abstract: [
-    'virtual',
-  ],
-  access: [],
-  alias: [],
-  async: [],
-  augments: [
-    'extends',
-  ],
-  author: [],
-  borrows: [],
-  callback: [],
-  class: [
-    'constructor',
-  ],
-  classdesc: [],
-  constant: [
-    'const',
-  ],
-  constructs: [],
-  copyright: [],
-  default: [
-    'defaultvalue',
-  ],
-  deprecated: [],
-  description: [
-    'desc',
-  ],
-  enum: [],
-  event: [],
-  example: [],
-  exports: [],
-  external: [
-    'host',
-  ],
-  file: [
-    'fileoverview',
-    'overview',
-  ],
-  fires: [
-    'emits',
-  ],
-  function: [
-    'func',
-    'method',
-  ],
-  generator: [],
-  global: [],
-  hideconstructor: [],
-  ignore: [],
-  implements: [],
-  inheritdoc: [],
-
-  // Allowing casing distinct from jsdoc `definitions.js` (required in Closure)
-  inheritDoc: [],
-
-  inner: [],
-  instance: [],
-  interface: [],
-  kind: [],
-  lends: [],
-  license: [],
-  listens: [],
-  member: [
-    'var',
-  ],
-  memberof: [],
-  'memberof!': [],
-  mixes: [],
-  mixin: [],
-
-  module: [],
-  name: [],
-  namespace: [],
-  override: [],
-  package: [],
-  param: [
-    'arg',
-    'argument',
-  ],
-  private: [],
-  property: [
-    'prop',
-  ],
-  protected: [],
-  public: [],
-  readonly: [],
-  requires: [],
-  returns: [
-    'return',
-  ],
-  see: [],
-  since: [],
-  static: [],
-  summary: [],
-
-  this: [],
-  throws: [
-    'exception',
-  ],
-  todo: [],
-  tutorial: [],
-  type: [],
-  typedef: [],
-  variation: [],
-  version: [],
-  yields: [
-    'yield',
-  ],
-};
-
-/**
- * @type {AliasedTags}
- */
-const typeScriptTags = {
-  ...jsdocTags,
-
-  // https://github.com/microsoft/TypeScript/issues/22160
-  // https://devblogs.microsoft.com/typescript/announcing-typescript-5-5/#the-jsdoc-import-tag
-  import: [],
-
-  // https://www.typescriptlang.org/tsconfig/#stripInternal
-  internal: [],
-
-  // https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#overload-support-in-jsdoc
-  overload: [],
-
-  // https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#satisfies-support-in-jsdoc
-  satisfies: [],
-
-  // `@template` is also in TypeScript per:
-  //      https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc
-  template: [],
-};
-
-/**
- * @type {AliasedTags}
- */
-const undocumentedClosureTags = {
-  // These are in Closure source but not in jsdoc source nor in the Closure
-  //  docs: https://github.com/google/closure-compiler/blob/master/src/com/google/javascript/jscomp/parsing/Annotation.java
-  closurePrimitive: [],
-  customElement: [],
-  expose: [],
-  hidden: [],
-  idGenerator: [],
-  meaning: [],
-  mixinClass: [],
-  mixinFunction: [],
-  ngInject: [],
-  owner: [],
-  typeSummary: [],
-  wizaction: [],
-};
-
-const {
-  /* eslint-disable no-unused-vars */
-  inheritdoc,
-  internal,
-  overload,
-  // Will be inverted to prefer `return`
-  returns,
-
-  satisfies,
-  /* eslint-enable no-unused-vars */
-  ...typeScriptTagsInClosure
-} = typeScriptTags;
-
-/**
- * @type {AliasedTags}
- */
-const closureTags = {
-  ...typeScriptTagsInClosure,
-  ...undocumentedClosureTags,
-
-  // From https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler
-  // These are all recognized in https://github.com/jsdoc/jsdoc/blob/master/packages/jsdoc/lib/jsdoc/tag/dictionary/definitions.js
-  //   except for the experimental `noinline` and the casing differences noted below
-
-  // Defined as a synonym of `const` in jsdoc `definitions.js`
-  define: [],
-
-  dict: [],
-  export: [],
-  externs: [],
-  final: [],
-
-  // With casing distinct from jsdoc `definitions.js`
-  implicitCast: [],
-
-  noalias: [],
-  nocollapse: [],
-  nocompile: [],
-  noinline: [],
-  nosideeffects: [],
-  polymer: [],
-  polymerBehavior: [],
-  preserve: [],
-
-  // Defined as a synonym of `interface` in jsdoc `definitions.js`
-  record: [],
-
-  return: [
-    'returns',
-  ],
-
-  struct: [],
-  suppress: [],
-
-  unrestricted: [],
-};
-
-export {
-  closureTags,
-  jsdocTags,
-  typeScriptTags,
-};