eslint-plugin-jsdoc/dist/rules/matchName.cjs

JSDoc linting rules for ESLint.

"use strict";

Object.defineProperty(exports, "__esModule", {
  value: true
});
exports.default = void 0;
var _iterateJsdoc = _interopRequireDefault(require("../iterateJsdoc.cjs"));
function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
var _default = exports.default = (0, _iterateJsdoc.default)(({
  context,
  info: {
    lastIndex
  },
  jsdoc,
  report,
  utils
}) => {
  const {
    match
  } = context.options[0] || {};
  if (!match) {
    report('Rule `no-restricted-syntax` is missing a `match` option.');
    return;
  }
  const {
    allowName,
    disallowName,
    replacement,
    tags = ['*']
  } = match[(/** @type {import('../iterateJsdoc.js').Integer} */lastIndex)];
  const allowNameRegex = allowName && utils.getRegexFromString(allowName);
  const disallowNameRegex = disallowName && utils.getRegexFromString(disallowName);
  let applicableTags = jsdoc.tags;
  if (!tags.includes('*')) {
    applicableTags = utils.getPresentTags(tags);
  }
  let reported = false;
  for (const tag of applicableTags) {
    const tagName = tag.name.replace(/^\[/v, '').replace(/(=.*)?\]$/v, '');
    const allowed = !allowNameRegex || allowNameRegex.test(tagName);
    const disallowed = disallowNameRegex && disallowNameRegex.test(tagName);
    const hasRegex = allowNameRegex || disallowNameRegex;
    if (hasRegex && allowed && !disallowed) {
      continue;
    }
    if (!hasRegex && reported) {
      continue;
    }
    const fixer = () => {
      for (const src of tag.source) {
        if (src.tokens.name) {
          src.tokens.name = src.tokens.name.replace(disallowNameRegex, replacement);
          break;
        }
      }
    };
    let {
      message
    } = match[(/** @type {import('../iterateJsdoc.js').Integer} */lastIndex)];
    if (!message) {
      if (hasRegex) {
        message = disallowed ? `Only allowing names not matching \`${disallowNameRegex}\` but found "${tagName}".` : `Only allowing names matching \`${allowNameRegex}\` but found "${tagName}".`;
      } else {
        message = `Prohibited context for "${tagName}".`;
      }
    }
    utils.reportJSDoc(message, hasRegex ? tag : null,
    // We could match up
    disallowNameRegex && replacement !== undefined ? fixer : null, false, {
      // Could also supply `context`, `comment`, `tags`
      allowName,
      disallowName,
      name: tagName
    });
    if (!hasRegex) {
      reported = true;
    }
  }
}, {
  matchContext: true,
  meta: {
    docs: {
      description: 'Reports the name portion of a JSDoc tag if matching or not matching a given regular expression.',
      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/match-name.md#repos-sticky-header'
    },
    fixable: 'code',
    schema: [{
      additionalProperties: false,
      properties: {
        match: {
          description: `\`match\` is a required option containing an array of objects which determine
the conditions whereby a name is reported as being problematic.

These objects can have any combination of the following groups of optional
properties, all of which act to confine one another.

Note that \`comment\`, even if targeting a specific tag, is used to match the
whole block. So if a \`comment\` finds its specific tag, it may still apply
fixes found by the likes of \`disallowName\` even when a different tag has the
disallowed name. An alternative is to ensure that \`comment\` finds the specific
tag of the desired tag and/or name and no \`disallowName\` (or \`allowName\`) is
supplied. In such a case, only one error will be reported, but no fixer will
be applied, however.`,
          items: {
            additionalProperties: false,
            properties: {
              allowName: {
                description: `Indicates which names are allowed for the given tag (or \`*\`).
Accepts a string regular expression (optionally wrapped between two
\`/\` delimiters followed by optional flags) used to match the name.`,
                type: 'string'
              },
              comment: {
                description: 'As with `context` but AST for the JSDoc block comment and types.',
                type: 'string'
              },
              context: {
                description: `AST to confine the allowing or disallowing to JSDoc blocks
associated with a particular context. See the
["AST and Selectors"](../#advanced-ast-and-selectors)
section of our Advanced docs for more on the expected format.`,
                type: 'string'
              },
              disallowName: {
                description: 'As with `allowName` but indicates names that are not allowed.',
                type: 'string'
              },
              message: {
                description: 'An optional custom message to use when there is a match.',
                type: 'string'
              },
              replacement: {
                description: `If \`disallowName\` is supplied and this value is present, it
will replace the matched \`disallowName\` text.`,
                type: 'string'
              },
              tags: {
                description: `This array should include tag names or \`*\` to indicate the
  match will apply for all tags (except as confined by any context
  properties). If \`*\` is not used, then these rules will only apply to
  the specified tags. If \`tags\` is omitted, then \`*\` is assumed.`,
                items: {
                  type: 'string'
                },
                type: 'array'
              }
            },
            type: 'object'
          },
          type: 'array'
        }
      },
      required: ['match'],
      type: 'object'
    }],
    type: 'suggestion'
  }
});
module.exports = exports.default;
//# sourceMappingURL=matchName.cjs.map