eslint-plugin-jsdoc 52.0.4 → 53.0.0

package/src/rules/checkAccess.js

@@ -1,45 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-const accessLevels = [
-  'package', 'private', 'protected', 'public',
-];
-
-export default iterateJsdoc(({
-  report,
-  utils,
-}) => {
-  utils.forEachPreferredTag('access', (jsdocParameter, targetTagName) => {
-    const desc = jsdocParameter.name + ' ' + jsdocParameter.description;
-
-    if (!accessLevels.includes(desc.trim())) {
-      report(
-        `Missing valid JSDoc @${targetTagName} level.`,
-        null,
-        jsdocParameter,
-      );
-    }
-  });
-  const accessLength = utils.getTags('access').length;
-  const individualTagLength = utils.getPresentTags(accessLevels).length;
-  if (accessLength && individualTagLength) {
-    report(
-      'The @access tag may not be used with specific access-control tags (@package, @private, @protected, or @public).',
-    );
-  }
-
-  if (accessLength > 1 || individualTagLength > 1) {
-    report(
-      'At most one access-control tag may be present on a jsdoc block.',
-    );
-  }
-}, {
-  checkPrivate: true,
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Checks that `@access` tags have a valid value.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-access.md#repos-sticky-header',
-    },
-    type: 'suggestion',
-  },
-});

package/src/rules/checkAlignment.js

@@ -1,63 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-/**
- * @param {string} string
- * @returns {string}
- */
-const trimStart = (string) => {
-  return string.replace(/^\s+/v, '');
-};
-
-export default iterateJsdoc(({
-  indent,
-  jsdocNode,
-  report,
-  sourceCode,
-}) => {
-  // `indent` is whitespace from line 1 (`/**`), so slice and account for "/".
-  const indentLevel = indent.length + 1;
-  const sourceLines = sourceCode.getText(jsdocNode).split('\n')
-    .slice(1)
-    .map((line) => {
-      return line.split('*')[0];
-    })
-    .filter((line) => {
-      return !trimStart(line).length;
-    });
-
-  /** @type {import('eslint').Rule.ReportFixer} */
-  const fix = (fixer) => {
-    const replacement = sourceCode.getText(jsdocNode).split('\n')
-      .map((line, index) => {
-        // Ignore the first line and all lines not starting with `*`
-        const ignored = !index || trimStart(line.split('*')[0]).length;
-
-        return ignored ? line : `${indent} ${trimStart(line)}`;
-      })
-      .join('\n');
-
-    return fixer.replaceText(jsdocNode, replacement);
-  };
-
-  sourceLines.some((line, lineNum) => {
-    if (line.length !== indentLevel) {
-      report('Expected JSDoc block to be aligned.', fix, {
-        line: lineNum + 1,
-      });
-
-      return true;
-    }
-
-    return false;
-  });
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Reports invalid alignment of JSDoc block asterisks.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-alignment.md#repos-sticky-header',
-    },
-    fixable: 'code',
-    type: 'layout',
-  },
-});

package/src/rules/checkExamples.js

@@ -1,589 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-import eslint, {
-  ESLint,
-} from 'eslint';
-import semver from 'semver';
-
-const {
-  // @ts-expect-error Older ESLint
-  CLIEngine,
-} = eslint;
-
-const zeroBasedLineIndexAdjust = -1;
-const likelyNestedJSDocIndentSpace = 1;
-const preTagSpaceLength = 1;
-
-// If a space is present, we should ignore it
-const firstLinePrefixLength = preTagSpaceLength;
-
-const hasCaptionRegex = /^\s*<caption>([\s\S]*?)<\/caption>/v;
-
-/**
- * @param {string} str
- * @returns {string}
- */
-const escapeStringRegexp = (str) => {
-  return str.replaceAll(/[.*+?^$\{\}\(\)\|\[\]\\]/gv, '\\$&');
-};
-
-/**
- * @param {string} str
- * @param {string} ch
- * @returns {import('../iterateJsdoc.js').Integer}
- */
-const countChars = (str, ch) => {
-  return (str.match(new RegExp(escapeStringRegexp(ch), 'gv')) || []).length;
-};
-
-/** @type {import('eslint').Linter.RulesRecord} */
-const defaultMdRules = {
-  // "always" newline rule at end unlikely in sample code
-  'eol-last': 0,
-
-  // Wouldn't generally expect example paths to resolve relative to JS file
-  'import/no-unresolved': 0,
-
-  // Snippets likely too short to always include import/export info
-  'import/unambiguous': 0,
-
-  'jsdoc/require-file-overview': 0,
-
-  // The end of a multiline comment would end the comment the example is in.
-  'jsdoc/require-jsdoc': 0,
-
-  // Unlikely to have inadvertent debugging within examples
-  'no-console': 0,
-
-  // Often wish to start `@example` code after newline; also may use
-  //   empty lines for spacing
-  'no-multiple-empty-lines': 0,
-
-  // Many variables in examples will be `undefined`
-  'no-undef': 0,
-
-  // Common to define variables for clarity without always using them
-  'no-unused-vars': 0,
-
-  // See import/no-unresolved
-  'node/no-missing-import': 0,
-  'node/no-missing-require': 0,
-
-  // Can generally look nicer to pad a little even if code imposes more stringency
-  'padded-blocks': 0,
-};
-
-/** @type {import('eslint').Linter.RulesRecord} */
-const defaultExpressionRules = {
-  ...defaultMdRules,
-  'chai-friendly/no-unused-expressions': 'off',
-  'no-empty-function': 'off',
-  'no-new': 'off',
-  'no-unused-expressions': 'off',
-  quotes: [
-    'error', 'double',
-  ],
-  semi: [
-    'error', 'never',
-  ],
-  strict: 'off',
-};
-
-/**
- * @param {string} text
- * @returns {[
- *   import('../iterateJsdoc.js').Integer,
- *   import('../iterateJsdoc.js').Integer
- * ]}
- */
-const getLinesCols = (text) => {
-  const matchLines = countChars(text, '\n');
-
-  const colDelta = matchLines ?
-    text.slice(text.lastIndexOf('\n') + 1).length :
-    text.length;
-
-  return [
-    matchLines, colDelta,
-  ];
-};
-
-export default iterateJsdoc(({
-  context,
-  globalState,
-  report,
-  utils,
-}) => {
-  if (semver.gte(ESLint.version, '8.0.0')) {
-    report(
-      'This rule does not work for ESLint 8+; you should disable this rule and use' +
-        'the processor mentioned in the docs.',
-      null,
-      {
-        column: 1,
-        line: 1,
-      },
-    );
-
-    return;
-  }
-
-  if (!globalState.has('checkExamples-matchingFileName')) {
-    globalState.set('checkExamples-matchingFileName', new Map());
-  }
-
-  const matchingFileNameMap = /** @type {Map<string, string>} */ (
-    globalState.get('checkExamples-matchingFileName')
-  );
-
-  const options = context.options[0] || {};
-  let {
-    exampleCodeRegex = null,
-    rejectExampleCodeRegex = null,
-  } = options;
-  const {
-    allowInlineConfig = true,
-    baseConfig = {},
-    captionRequired = false,
-    checkDefaults = false,
-    checkEslintrc = true,
-    checkParams = false,
-    checkProperties = false,
-    configFile,
-    matchingFileName = null,
-    matchingFileNameDefaults = null,
-    matchingFileNameParams = null,
-    matchingFileNameProperties = null,
-    noDefaultExampleRules = false,
-    paddedIndent = 0,
-    reportUnusedDisableDirectives = true,
-  } = options;
-
-  // Make this configurable?
-  /**
-   * @type {never[]}
-   */
-  const rulePaths = [];
-
-  const mdRules = noDefaultExampleRules ? undefined : defaultMdRules;
-
-  const expressionRules = noDefaultExampleRules ? undefined : defaultExpressionRules;
-
-  if (exampleCodeRegex) {
-    exampleCodeRegex = utils.getRegexFromString(exampleCodeRegex);
-  }
-
-  if (rejectExampleCodeRegex) {
-    rejectExampleCodeRegex = utils.getRegexFromString(rejectExampleCodeRegex);
-  }
-
-  /**
-   * @param {{
-   *   filename: string,
-   *   defaultFileName: string|undefined,
-   *   source: string,
-   *   targetTagName: string,
-   *   rules?: import('eslint').Linter.RulesRecord|undefined,
-   *   lines?: import('../iterateJsdoc.js').Integer,
-   *   cols?: import('../iterateJsdoc.js').Integer,
-   *   skipInit?: boolean,
-   *   sources?: {
-   *     nonJSPrefacingCols: import('../iterateJsdoc.js').Integer,
-   *     nonJSPrefacingLines: import('../iterateJsdoc.js').Integer,
-   *     string: string,
-   *   }[],
-   *   tag?: import('comment-parser').Spec & {
-   *     line?: import('../iterateJsdoc.js').Integer,
-   *   }|{
-   *     line: import('../iterateJsdoc.js').Integer,
-   *   }
-   * }} cfg
-   */
-  const checkSource = ({
-    cols = 0,
-    defaultFileName,
-    filename,
-    lines = 0,
-    rules = expressionRules,
-    skipInit,
-    source,
-    sources = [],
-    tag = {
-      line: 0,
-    },
-    targetTagName,
-  }) => {
-    if (!skipInit) {
-      sources.push({
-        nonJSPrefacingCols: cols,
-        nonJSPrefacingLines: lines,
-        string: source,
-      });
-    }
-
-    /**
-     * @param {{
-     *   nonJSPrefacingCols: import('../iterateJsdoc.js').Integer,
-     *   nonJSPrefacingLines: import('../iterateJsdoc.js').Integer,
-     *   string: string
-     * }} cfg
-     */
-    const checkRules = function ({
-      nonJSPrefacingCols,
-      nonJSPrefacingLines,
-      string,
-    }) {
-      const cliConfig = {
-        allowInlineConfig,
-        baseConfig,
-        configFile,
-        reportUnusedDisableDirectives,
-        rulePaths,
-        rules,
-        useEslintrc: checkEslintrc,
-      };
-      const cliConfigStr = JSON.stringify(cliConfig);
-
-      const src = paddedIndent ?
-        string.replaceAll(new RegExp(`(^|\n) {${paddedIndent}}(?!$)`, 'gv'), '\n') :
-        string;
-
-      // Programmatic ESLint API: https://eslint.org/docs/developer-guide/nodejs-api
-      const fileNameMapKey = filename ?
-        'a' + cliConfigStr + filename :
-        'b' + cliConfigStr + defaultFileName;
-      const file = filename || defaultFileName;
-      let cliFile;
-      if (matchingFileNameMap.has(fileNameMapKey)) {
-        cliFile = matchingFileNameMap.get(fileNameMapKey);
-      } else {
-        const cli = new CLIEngine(cliConfig);
-        let config;
-        if (filename || checkEslintrc) {
-          config = cli.getConfigForFile(file);
-        }
-
-        // We need a new instance to ensure that the rules that may only
-        //  be available to `file` (if it has its own `.eslintrc`),
-        //  will be defined.
-        cliFile = new CLIEngine({
-          allowInlineConfig,
-          baseConfig: {
-            ...baseConfig,
-            ...config,
-          },
-          configFile,
-          reportUnusedDisableDirectives,
-          rulePaths,
-          rules,
-          useEslintrc: false,
-        });
-        matchingFileNameMap.set(fileNameMapKey, cliFile);
-      }
-
-      const {
-        results: [
-          {
-            messages,
-          },
-        ],
-      } = cliFile.executeOnText(src);
-
-      if (!('line' in tag)) {
-        tag.line = tag.source[0].number;
-      }
-
-      // NOTE: `tag.line` can be 0 if of form `/** @tag ... */`
-      const codeStartLine = /**
-                             * @type {import('comment-parser').Spec & {
-                             *     line: import('../iterateJsdoc.js').Integer,
-                             * }}
-                             */ (tag).line + nonJSPrefacingLines;
-      const codeStartCol = likelyNestedJSDocIndentSpace;
-
-      for (const {
-        column,
-        line,
-        message,
-        ruleId,
-        severity,
-      } of messages) {
-        const startLine = codeStartLine + line + zeroBasedLineIndexAdjust;
-        const startCol = codeStartCol + (
-
-          // This might not work for line 0, but line 0 is unlikely for examples
-          line <= 1 ? nonJSPrefacingCols + firstLinePrefixLength : preTagSpaceLength
-        ) + column;
-
-        report(
-          '@' + targetTagName + ' ' + (severity === 2 ? 'error' : 'warning') +
-            (ruleId ? ' (' + ruleId + ')' : '') + ': ' +
-            message,
-          null,
-          {
-            column: startCol,
-            line: startLine,
-          },
-        );
-      }
-    };
-
-    for (const targetSource of sources) {
-      checkRules(targetSource);
-    }
-  };
-
-  /**
-   *
-   * @param {string} filename
-   * @param {string} [ext] Since `eslint-plugin-markdown` v2, and
-   *   ESLint 7, this is the default which other JS-fenced rules will used.
-   *   Formerly "md" was the default.
-   * @returns {{defaultFileName: string|undefined, filename: string}}
-   */
-  const getFilenameInfo = (filename, ext = 'md/*.js') => {
-    let defaultFileName;
-    if (!filename) {
-      const jsFileName = context.getFilename();
-      if (typeof jsFileName === 'string' && jsFileName.includes('.')) {
-        defaultFileName = jsFileName.replace(/\.[^.]*$/v, `.${ext}`);
-      } else {
-        defaultFileName = `dummy.${ext}`;
-      }
-    }
-
-    return {
-      defaultFileName,
-      filename,
-    };
-  };
-
-  if (checkDefaults) {
-    const filenameInfo = getFilenameInfo(matchingFileNameDefaults, 'jsdoc-defaults');
-    utils.forEachPreferredTag('default', (tag, targetTagName) => {
-      if (!tag.description.trim()) {
-        return;
-      }
-
-      checkSource({
-        source: `(${utils.getTagDescription(tag)})`,
-        targetTagName,
-        ...filenameInfo,
-      });
-    });
-  }
-
-  if (checkParams) {
-    const filenameInfo = getFilenameInfo(matchingFileNameParams, 'jsdoc-params');
-    utils.forEachPreferredTag('param', (tag, targetTagName) => {
-      if (!tag.default || !tag.default.trim()) {
-        return;
-      }
-
-      checkSource({
-        source: `(${tag.default})`,
-        targetTagName,
-        ...filenameInfo,
-      });
-    });
-  }
-
-  if (checkProperties) {
-    const filenameInfo = getFilenameInfo(matchingFileNameProperties, 'jsdoc-properties');
-    utils.forEachPreferredTag('property', (tag, targetTagName) => {
-      if (!tag.default || !tag.default.trim()) {
-        return;
-      }
-
-      checkSource({
-        source: `(${tag.default})`,
-        targetTagName,
-        ...filenameInfo,
-      });
-    });
-  }
-
-  const tagName = /** @type {string} */ (utils.getPreferredTagName({
-    tagName: 'example',
-  }));
-  if (!utils.hasTag(tagName)) {
-    return;
-  }
-
-  const matchingFilenameInfo = getFilenameInfo(matchingFileName);
-
-  utils.forEachPreferredTag('example', (tag, targetTagName) => {
-    let source = /** @type {string} */ (utils.getTagDescription(tag));
-    const match = source.match(hasCaptionRegex);
-
-    if (captionRequired && (!match || !match[1].trim())) {
-      report('Caption is expected for examples.', null, tag);
-    }
-
-    source = source.replace(hasCaptionRegex, '');
-    const [
-      lines,
-      cols,
-    ] = match ? getLinesCols(match[0]) : [
-      0, 0,
-    ];
-
-    if (exampleCodeRegex && !exampleCodeRegex.test(source) ||
-      rejectExampleCodeRegex && rejectExampleCodeRegex.test(source)
-    ) {
-      return;
-    }
-
-    const sources = [];
-    let skipInit = false;
-    if (exampleCodeRegex) {
-      let nonJSPrefacingCols = 0;
-      let nonJSPrefacingLines = 0;
-
-      let startingIndex = 0;
-      let lastStringCount = 0;
-
-      let exampleCode;
-      exampleCodeRegex.lastIndex = 0;
-      while ((exampleCode = exampleCodeRegex.exec(source)) !== null) {
-        const {
-          '0': n0,
-          '1': n1,
-          index,
-        } = exampleCode;
-
-        // Count anything preceding user regex match (can affect line numbering)
-        const preMatch = source.slice(startingIndex, index);
-
-        const [
-          preMatchLines,
-          colDelta,
-        ] = getLinesCols(preMatch);
-
-        let nonJSPreface;
-        let nonJSPrefaceLineCount;
-        if (n1) {
-          const idx = n0.indexOf(n1);
-          nonJSPreface = n0.slice(0, idx);
-          nonJSPrefaceLineCount = countChars(nonJSPreface, '\n');
-        } else {
-          nonJSPreface = '';
-          nonJSPrefaceLineCount = 0;
-        }
-
-        nonJSPrefacingLines += lastStringCount + preMatchLines + nonJSPrefaceLineCount;
-
-        // Ignore `preMatch` delta if newlines here
-        if (nonJSPrefaceLineCount) {
-          const charsInLastLine = nonJSPreface.slice(nonJSPreface.lastIndexOf('\n') + 1).length;
-
-          nonJSPrefacingCols += charsInLastLine;
-        } else {
-          nonJSPrefacingCols += colDelta + nonJSPreface.length;
-        }
-
-        const string = n1 || n0;
-        sources.push({
-          nonJSPrefacingCols,
-          nonJSPrefacingLines,
-          string,
-        });
-        startingIndex = exampleCodeRegex.lastIndex;
-        lastStringCount = countChars(string, '\n');
-        if (!exampleCodeRegex.global) {
-          break;
-        }
-      }
-
-      skipInit = true;
-    }
-
-    checkSource({
-      cols,
-      lines,
-      rules: mdRules,
-      skipInit,
-      source,
-      sources,
-      tag,
-      targetTagName,
-      ...matchingFilenameInfo,
-    });
-  });
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-examples.md#repos-sticky-header',
-    },
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          allowInlineConfig: {
-            default: true,
-            type: 'boolean',
-          },
-          baseConfig: {
-            type: 'object',
-          },
-          captionRequired: {
-            default: false,
-            type: 'boolean',
-          },
-          checkDefaults: {
-            default: false,
-            type: 'boolean',
-          },
-          checkEslintrc: {
-            default: true,
-            type: 'boolean',
-          },
-          checkParams: {
-            default: false,
-            type: 'boolean',
-          },
-          checkProperties: {
-            default: false,
-            type: 'boolean',
-          },
-          configFile: {
-            type: 'string',
-          },
-          exampleCodeRegex: {
-            type: 'string',
-          },
-          matchingFileName: {
-            type: 'string',
-          },
-          matchingFileNameDefaults: {
-            type: 'string',
-          },
-          matchingFileNameParams: {
-            type: 'string',
-          },
-          matchingFileNameProperties: {
-            type: 'string',
-          },
-          noDefaultExampleRules: {
-            default: false,
-            type: 'boolean',
-          },
-          paddedIndent: {
-            default: 0,
-            type: 'integer',
-          },
-          rejectExampleCodeRegex: {
-            type: 'string',
-          },
-          reportUnusedDisableDirectives: {
-            default: true,
-            type: 'boolean',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});