eslint-plugin-jsdoc/dist/rules/requireFileOverview.cjs.map

JSDoc linting rules for ESLint.

{"version":3,"file":"requireFileOverview.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/requireFileOverview.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nconst defaultTags = {\n  file: {\n    initialCommentsOnly: true,\n    mustExist: true,\n    preventDuplicates: true,\n  },\n};\n\n/**\n * @param {import('../iterateJsdoc.js').StateObject} state\n * @returns {void}\n */\nconst setDefaults = (state) => {\n  // First iteration\n  if (!state.globalTags) {\n    state.globalTags = true;\n    state.hasDuplicates = {};\n    state.hasTag = {};\n    state.hasNonCommentBeforeTag = {};\n  }\n};\n\nexport default iterateJsdoc(({\n  context,\n  jsdocNode,\n  state,\n  utils,\n}) => {\n  const {\n    tags = defaultTags,\n  } = context.options[0] || {};\n\n  setDefaults(state);\n\n  for (const tagName of Object.keys(tags)) {\n    const targetTagName = /** @type {string} */ (utils.getPreferredTagName({\n      tagName,\n    }));\n\n    const hasTag = Boolean(targetTagName && utils.hasTag(targetTagName));\n\n    state.hasTag[tagName] = hasTag || state.hasTag[tagName];\n\n    const hasDuplicate = state.hasDuplicates[tagName];\n\n    if (hasDuplicate === false) {\n      // Was marked before, so if a tag now, is a dupe\n      state.hasDuplicates[tagName] = hasTag;\n    } else if (!hasDuplicate && hasTag) {\n      // No dupes set before, but has first tag, so change state\n      //   from `undefined` to `false` so can detect next time\n      state.hasDuplicates[tagName] = false;\n      state.hasNonCommentBeforeTag[tagName] = state.hasNonComment &&\n        state.hasNonComment < jsdocNode.range[0];\n    }\n  }\n}, {\n  exit ({\n    context,\n    state,\n    utils,\n  }) {\n    setDefaults(state);\n    const {\n      tags = defaultTags,\n    } = context.options[0] || {};\n\n    for (const [\n      tagName,\n      {\n        initialCommentsOnly = false,\n        mustExist = false,\n        preventDuplicates = false,\n      },\n    ] of Object.entries(tags)) {\n      const obj = utils.getPreferredTagNameObject({\n        tagName,\n      });\n      if (obj && typeof obj === 'object' && 'blocked' in obj) {\n        utils.reportSettings(\n          `\\`settings.jsdoc.tagNamePreference\\` cannot block @${obj.tagName} ` +\n          'for the `require-file-overview` rule',\n        );\n      } else {\n        const targetTagName = (\n          obj && typeof obj === 'object' && obj.replacement\n        ) || obj;\n        if (mustExist && !state.hasTag[tagName]) {\n          utils.reportSettings(`Missing @${targetTagName}`);\n        }\n\n        if (preventDuplicates && state.hasDuplicates[tagName]) {\n          utils.reportSettings(\n            `Duplicate @${targetTagName}`,\n          );\n        }\n\n        if (initialCommentsOnly &&\n            state.hasNonCommentBeforeTag[tagName]\n        ) {\n          utils.reportSettings(\n            `@${targetTagName} should be at the beginning of the file`,\n          );\n        }\n      }\n    }\n  },\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Checks that all files have one `@file`, `@fileoverview`, or `@overview` tag at the beginning of the file.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-file-overview.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          tags: {\n            description: `The keys of this object are tag names, and the values are configuration\nobjects indicating what will be checked for these whole-file tags.\n\nEach configuration object has 3 potential boolean keys (which default\nto \\`false\\` when this option is supplied).\n\n1. \\`mustExist\\` - enforces that all files have a \\`@file\\`, \\`@fileoverview\\`, or \\`@overview\\` tag.\n2. \\`preventDuplicates\\` - enforces that duplicate file overview tags within a given file will be reported\n3. \\`initialCommentsOnly\\` - reports file overview tags which are not, as per\n  [the docs](https://jsdoc.app/tags-file.html), \"at the beginning of\n  the file\"–where beginning of the file is interpreted in this rule\n  as being when the overview tag is not preceded by anything other than\n  a comment.\n\nWhen no \\`tags\\` is present, the default is:\n\n\\`\\`\\`json\n{\n  \"file\": {\n    \"initialCommentsOnly\": true,\n    \"mustExist\": true,\n    \"preventDuplicates\": true,\n  }\n}\n\\`\\`\\`\n\nYou can add additional tag names and/or override \\`file\\` if you supply this\noption, e.g., in place of or in addition to \\`file\\`, giving other potential\nfile global tags like \\`@license\\`, \\`@copyright\\`, \\`@author\\`, \\`@module\\` or\n\\`@exports\\`, optionally restricting them to a single use or preventing them\nfrom being preceded by anything besides comments.\n\nFor example:\n\n\\`\\`\\`js\n{\n  \"license\": {\n    \"mustExist\": true,\n    \"preventDuplicates\": true,\n  }\n}\n\\`\\`\\`\n\nThis would require one and only one \\`@license\\` in the file, though because\n\\`initialCommentsOnly\\` is absent and defaults to \\`false\\`, the \\`@license\\`\ncan be anywhere.\n\nIn the case of \\`@license\\`, you can use this rule along with the\n\\`check-values\\` rule (with its \\`allowedLicenses\\` or \\`licensePattern\\` options),\nto enforce a license whitelist be present on every JS file.\n\nNote that if you choose to use \\`preventDuplicates\\` with \\`license\\`, you still\nhave a way to allow multiple licenses for the whole page by using the SPDX\n\"AND\" expression, e.g., \\`@license (MIT AND GPL-3.0)\\`.\n\nNote that the tag names are the main JSDoc tag name, so you should use \\`file\\`\nin this configuration object regardless of whether you have configured\n\\`fileoverview\\` instead of \\`file\\` on \\`tagNamePreference\\` (i.e., \\`fileoverview\\`\nwill be checked, but you must use \\`file\\` on the configuration object).`,\n            patternProperties: {\n              '.*': {\n                additionalProperties: false,\n                properties: {\n                  initialCommentsOnly: {\n                    type: 'boolean',\n                  },\n                  mustExist: {\n                    type: 'boolean',\n                  },\n                  preventDuplicates: {\n                    type: 'boolean',\n                  },\n                },\n                type: 'object',\n              },\n            },\n            type: 'object',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n  nonComment ({\n    node,\n    state,\n  }) {\n    if (!state.hasNonComment) {\n      state.hasNonComment = /** @type {[number, number]} */ (node.range)?.[0];\n    }\n  },\n});\n"],"mappings":"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ACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,yEAAyE;UAC7D,iBAAiB,EAAE;YACjB,IAAI,EAAE;cACJ,oBAAoB,EAAE,KAAK;cAC3B,UAAU,EAAE;gBACV,mBAAmB,EAAE;kBACnB,IAAI,EAAE;gBACR,CAAC;gBACD,SAAS,EAAE;kBACT,IAAI,EAAE;gBACR,CAAC;gBACD,iBAAiB,EAAE;kBACjB,IAAI,EAAE;gBACR;cACF,CAAC;cACD,IAAI,EAAE;YACR;UACF,CAAC;UACD,IAAI,EAAE;QACR;MACF,CAAC;MACD,IAAI,EAAE;IACR,CAAC,CACF;IACD,IAAI,EAAE;EACR,CAAC;EACD,UAAU,CAAE;IACV,IAAI;IACJ;EACF,CAAC,EAAE;IACD,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE;MACxB,KAAK,CAAC,aAAa,GAAG,+BAAiC,IAAI,CAAC,KAAK,GAAI,CAAC,CAAC;IACzE;EACF;AACF,CAAC,CAAC;AAAA","ignoreList":[]}